Alephium CLI

Alephium CLI is a tool for creating projects, compiling contracts, and deploying contracts.

Create a Project

We can create a new project using the init command, the -t parameter is used to specify the project type:

npx @alephium/cli init my-dapp -t react

There are three available project types:

• base: Create a Node.js project, this is the default type if the -t parameter is not specified
• react: Create a React project
• nextjs: Create a Next.js project

Configuration

In order to use the Alephium CLI, we need to have a configuration file. The default config file is alephium.config.ts/js located in the project root directory. The following is an example of a configuration file:

alephium.config.ts

import { Configuration } from '@alephium/cli'

const configuration: Configuration = {
  // The `networks` field specifies configurations for different networks. It supports three types of networks: devnet, testnet, and mainnet
  networks: {
    devnet: {
      // The `nodeUrl` is the url of the full node
      nodeUrl: 'http://localhost:22973',
      // The purpose of private key is for deploying contracts. Since Alephium currently has 4 groups,
      // the maximum length of `privateKeys` is 4, and each group can have at most one private key.
      // If you only need to deploy contracts to one group, you only need to specify one private key.
      privateKeys: ['a642942e67258589cd2b1822c631506632db5a12aabcf413604e785300d762a5'],
      // The `confirmations` field is used to specify the number of block confirmations to wait for
      // after contract deployment. This is an optional config. If it is not specified, it defaults
      // to 1 for devnet and 2 for testnet and mainnet.
      confirmations: 1
    }
  }
}

// You must export the `configuration` from the config file
export default configuration

In most cases, we only need to specify the networks config. The other optional configs work well by default, but we can also configure them if needed:

Name	Description
sourceDir	Location for contract code, it is <project_root>/contracts by default
artifactDir	Location for compiled contract artifacts, it is <project_root>/artifacts by default
deployToMultipleGroupsInParallel	If the contract needs to be deployed to multiple groups, this config specifies whether to deploy them in parallel, it is true by default
deploymentScriptDir	Location for deployment scripts, it is <project_root>/scripts by default
deploymentsDir	Location for contract deployments, it is <project_root>/deployments by default
compilerOptions
	ignoreUnusedConstantsWarnings
	ignoreUnusedVariablesWarnings
	ignoreUnusedFieldsWarnings
	ignoreUnusedPrivateFunctionsWarnings
	ignoreUpdateFieldsCheckWarnings Ignore compiler warnings if contract functions update contract fields but does not have the updateField annotation
	ignoreCheckExternalCallerWarnings Ignore compiler warnings if public contract functions does not have the checkExternalCaller annotation
	errorOnWarnings Compiler warnings will be treated as errors if this config is enabled
skipRecompile	Specify whether contract code should be recompiled when deploying contracts, it is false by default
forceRecompile	The purpose of this config is to maintain backward compatibility, it is disabled by default. More concretely: If this config is disabled and the contract code has already been deployed to the testnet/mainnet without any updates, then no new bytecode will be generated for the contract If this config is disabled and the contract code has already been deployed to the testnet/mainnet but the contract code has been updated, then new bytecode will be generated for the contract If this config is enabled or the contract code has not been deployed to the testnet/mainnet, then new bytecode will be generated for the contract
enableDebugMode	Alephium CLI will print out network requests and error stack traces if enabled

Compile Contracts

After project is created, we can use the compile command to compile contract code, the -n parameter is used to specify the network type:

npx @alephium/cli compile -n devnet

The compile command compiles contract code, saves the compiled artifacts, and generates TypeScript code based on the artifacts. We can use the generated TypeScript code to interact with the contracts.

Deploy Contracts

To deploy contracts, we need to write the contract deployment scripts. The file names of the deployment scripts must follow this regular expression pattern: ^([0-9]+)_.*.(ts|js)$, and they will be executed according to the same numerical order of their file names. Please refer to the documentation here for writing deployment scripts.

We can use the deploy command to deploy contracts, the -n parameter is used to specify the network type:

npx @alephium/cli deploy -n devnet

When contract deployment is successful, deployment results will be saved to the artifacts/.deployment.<network_id>.json file, and it will generate TypeScript code for loading deployment results.

After contracts are well tested, we can deploy them to the Mainnet by simply switching the network type:

npx @alephium/cli deploy -n mainnet