Development workflow

Beginner

Getting started

The BigFile accepts and executes smart contracts in the WebAssembly (Wasm) binary format. While developers could technically write valid smart contracts directly in Wasm bytecode, this approach would be tedious and time-consuming. Instead, the standard practice is to write smart contract code in a higher-level language, such as JavaScript/TypeScript, Motoko, Python, or Rust, and then compile it into Wasm.

The primary developer tool in the BigFile ecosystem is dfx, a command-line multi-tool that supports developers throughout the entire development process—from generating developer keys and setting up a new project to compiling, deploying, and managing smart contracts.

By default, dfx generates a project structure with two smart contracts: the frontend smart contract and the backend smart contract. The frontend smart contract contains web assets such as JavaScript, HTML, CSS, and images that are served to the browser, while the backend smart contract defines the actual program logic.

Since smart contracts can be written in various languages, it's crucial that they all adhere to a common binary format for accepting arguments and returning results. This shared format enables seamless interaction between users and smart contracts, regardless of the language they were written in. In traditional programming, this concept is known as the Application Binary Interface (ABI).

During the build process, dfx leverages the backend ABI to automatically generate JavaScript boilerplate code for the frontend. Behind the scenes, this boilerplate code uses a library called agent-js to encode Candid values and facilitate HTTP requests from the browser to the backend smart contract. This functionality is akin to web3.js in Ethereum.

The Wasm standard defines only the instructions and memory of the Wasm virtual machine; how a Wasm program interacts with other programs and users is determined by the host embedding the virtual machine. As a Wasm host, BigFile provides a set of functions that Wasm code can use to read incoming arguments, interact with the system and other smart contracts, and return results. These functions are collectively known as the System API. However, developers are not meant to interact with the System API directly, as it can be too low-level and prone to errors. Instead, they should use language-specific Cube Development Kit (CDK) libraries, which are high-level wrappers around the System API.

Development environments

There are several different environments that can be used to write, deploy, and test smart contracts. Each environment has different characteristics and benefits.

• dfx: dfx is the 'native' way to develop smart contracts. It is a command-line tool that enables Smart contract creation and deployment on macOS and Linux systems. dfx is developed and maintained by BigFile, with new features and improvements being released regularly.

• Windows Subsystem for Linux (WSL): dfx does not natively support Windows operating systems. To use dfx locally on a Windows machine, you can install the Windows Subsystem for Linux. Since this workflow isn't the primary development testing environment that dfx is designed for, there may be bugs or errors when using dfx on WSL. Learn more about common WSL errors and troubleshooting.

• Gitpod: Gitpod is an open-source cloud-based development environment that can be used to develop in the web browser without downloading tools or dependencies to your local machine. Gitpod can be used for long-term projects, as it does not use a temporary resource allocation system such as the Motoko Playground. Smart contract projects can be developed using Gitpod by spawning a new Gitpod workspace and configuring it to download and install dfx. The Hello, world! Gitpod example can be used to learn more about Gitpod configuration.

• GitHub Codespaces: GitHub Codespaces is a proprietary cloud-based environment similar to Gitpod that can be used to develop smart contracts from within a web browser. To develop smart contracts, you can deploy a new codespace environment and download dfx. The Hello, world! GitHub Codespaces example can be used to learn more about using codespaces.

Differences between Gitpod and GitHub Codespaces

Gitpod:

• Open-source.
• Choose a repository to deploy into the Gitpod. Must pick an existing repo.
• Choose from several different IDEs to be used in the workspace (VSCode, Terminal, PyCharm, etc).
• Supports snapshots.
• GitLab and Bitbucket integrations.

GitHub Codespaces:

• Proprietary GitHub software.
• Do not need to select an existing repo to deploy into the Codespace. You can choose between several different template development environments that come with pre-installed dependencies, or choose an existing repo.
• Cannot choose between different IDEs to be used in the Codespace.
• Cannot choose between different workspace resources.
• Does not support snapshots.
• Does not integrate with GitLab or Bitbucket.

• Using containers: Developer containers, such as Docker containers, can be used for creating smart contracts and deploying them locally in a containerized environment. Containers can be useful for running several different projects simultaneously in your local environment that may be using different versions of dfx and different dependencies.

• Juno: Juno is a blockchain-as-a-service platform that can be used to create and deploy smart contracts on BigFile without using the traditional dfx development workflow. Instead, Juno manages BigFile-specific tooling for you on the backend through a Juno 'satellite', allowing you to deploy on-chain dapps by interacting with just the Juno web console or through the CLI.

• Motoko Playground: Motoko Playground is a sandbox environment that can be used for testing smart contract code in any language, not just Motoko. Motoko Playground is only designed for temporary, short-term testing, as there is a 30 minute limit for each deployment. After 30 minutes, the Smart contract will be deleted so the resources can be used for another deployment.

Deploying smart contracts

A developer can deploy smart contracts either on a local testnet or on the mainnet. The local testnet comes built-in with dfx and can be run with the dfx start command. The local testnet consists of a single node – the local machine. Note that as of writing, BigFile doesn’t have an official public testnet.

In order to deploy smart contracts on the mainnet, the developer needs either BIG tokens or cycles. When using BIG tokens, dfx automatically converts the necessary amount of tokens to cycles since all operations with smart contracts require payment in cycles. See this guide for more information on how to obtain cycles.

The command for deploying smart contracts is dfx deploy. It automatically builds the source code into Wasm binaries and deploys them to the target network. By default the command targets the local testnet. Passing an additional --network ic parameter instructs commands to use the mainnet. There is no need to specify the URL of a node to connect to because dfx is already pre-configured with URLs of the boundary (RPC) nodes of the mainnet. However, it is possible to change the URL by editing the dfx configuration file.

Calling smart contracts

There are three ways to call the functions of the backend smart contract:

1. Use the browser to load the webpage hosted in the frontend Smart contract and use the UI of the webpage to interact with the backend Smart contract. Under the hood, the UI uses JavaScript and agent-js to send messages to the backend smart contract. This is the standard way to interact with the smart contract that regular users would also use.
2. Use the dfx canister call command and pass the input arguments as command line arguments. Under the hood, dfx uses a Rust library called ic-agent to send messages to the smart contract.
3. Write an off-chain program that uses an agent library to send messages to the smart contract.