Local Development

Developing using the Web Deploy will only take you so far. Eventually, you will want to develop locally on your machine, so that you can easily use version control, your favorite editor, and other tools that you are used to.

This guide will walk you through setting up your local development environment using Contract-Flow.

Creating a new project

You don't need to install the contract-flow CLI locally, you can use npx for all commands.

contract-flow create <project_name> [optional_directory] 

This will create a project structure that looks like this:

📂 contracts
  📄 contract.cpp
📂 deployments
  📄 gf.ts
  📄 gftestnet.ts
📂 tests
  📄 contract.spec.ts
🔐 .env
📄 .gitignore
📄 contract-flow.config.js
📄 package.json

Developing contracts

The contract.cpp file inside of contracts already has a simple contract that you can use to get started.

Creating new contracts

You can either manually create a contract, copy an existing one, or use the scaffold CLI.

npx contract-flow scaffold contract <name> [optional_directory]

Building contracts

In order to test or deploy your contracts, you will need the .wasm and .abi files. To get them from your C++ files, you can use the CLI build command from your directory root.

npx contract-flow build

All build files will be saved to the build/ directory.

📂 build
  📄 contract.abi
  📄 contract.wasm
📂 contracts
  📄 contract.cpp

Testing contracts

Testing using Contract-Flow uses VeRT, an emulator for GlobalForce. You can head over to the testing guide if you want to learn about writing tests.

npx contract-flow test [--build]

Using the build option will simply batch both a build and test job together. It is no different than running build before test.

You can also scaffold a new test:

npx contract-flow scaffold test <name> [optional_directory]

Deploying contracts

Contract-Flow is able to deploy contracts to any Antelope network. The default that comes with new projects is the GlobalForce TestNet network, a common testnet.

The config file

A lot of the setup for deployments is done in the contract-flow.config.js file at the root of your project.

It exports a JSON object that includes network property which defines the chain, and accounts you need to deploy contracts.

networks:{
    gftestnet: {
        node_url: 'https://dev-history.globalforce.io',
        chain: 'gftestnet',
        accounts: [
            {
                name: 'youraccount',
                // permission: 'owner', // defaults to active
                private_key: process.env.PRIVATE_KEY
            }
        ]
    },
    gf: {
        node_url: 'https://history.globalforce.io',
        chain: 'gf',
        accounts: [
            {
                name: 'youraccount',
                // permission: 'owner', // defaults to active
                private_key: process.env.PRIVATE_KEY
            }
        ]
    }
}

The key for the network

The name of your deployment file in the deployments directory must always match the name of the key in the networks object. For instance, above we have defined the gftestnet network, and we also have a deployments/gftestnet.ts file.

If you wanted to have a Mainnet file, you would add both the gf key in networks and a deployments/gf.ts deployment file.

Specifying a node

You can either use the chain property to specify a chain, or you can use the node_url property to specify a specific node endpoint. You can find endpoints here Two common ones are:

• GlobalForce TestNet
• GlobalForce

Registering accounts

In order for the deployment script to know what keys belong to which accounts, you need to specify them here. The accounts property is an array of account definitions that include the following properties.

Property	Description
name	The name of the account
permission	The permission level of the account (defaults to active)
private_key	The private key of the account

Using environment variables

The project includes a .env file that you can use to store your private keys. This file is ignored by git, so you can safely store your keys here.

PRIVATE_KEY=your_private_key

Please make sure to never commit your .env file to a public repository, or use private keys in plain text in the config file.

Deployment files

The deployment files are written in JavaScript and are used to deploy contracts to the network.

They are injected with a deployer object that has the following properties:

Property	Description
accounts	An array of account definitions
sessions	An object that holds the current wharfkit session for each account
deploy	A function that you can use to deploy a contract and returns a wharfkit contract

module.exports = async (deployer) => {

    const contract = await deployer.deploy('someaccount', 'build/mycontract', {
        // Allows the contract to be able to send tokens from itself
        addCode: true
    }).catch(err => {
        console.error(err)
        process.exit(1);
    })

    // do other stuff here...
}

Creating deployments

You can either manually create a deployment, copy an existing one, or use the scaffold CLI.

npx contract-flow scaffold deployment <network> [optional_directory]

Deploying contracts

To deploy a contract, you can use the CLI deploy command.

npx contract-flow deploy <network> [--build]

Troubleshooting

Sometimes you run into problems. If you have anything that isn't on this list, please reach out in the Telegram group.

Multi-contract support

If you have multiple contracts in your project, then the compiler won't know which .cpp file is the entry file into that specific contract.

To fix this, you can change the suffix to .entry.cpp for each contract, and you will then get back named builds for each.

📂 build
  📄 game.abi
  📄 game.wasm
  📄 token.abi
  📄 token.wasm
📂 contracts
  📄 game.entry.cpp
  📄 token.entry.cpp

You also can use this CLI to create a new project with a frontend and contracts.

npm create globalforce@latest myproject

Follow the prompts, and it will set up a barebones project with a simple contract, tests, and deployment scripts as well as a frontend of your choosing (SvelteKit, Next.js (react), or Nuxt (vue)).