Project API

Configuration

Creating a project

$ npx @hackbg/fadroma@latest create

import Project from '@hackbg/fadroma'

const root = tmpDir()

let project: Project = new Project({
  root: `${root}/test-project-1`,
  name: 'test-project-1',
  templates: {
    test1: { crate: 'test1' },
    test2: { crate: 'test2' },
  }
})
  .create()
  .status()
  .cargoUpdate()

Defining new contracts

$ npm exec fadroma add

const test1 = project.getTemplate('test1')
assert(test1 instanceof Template)

const test3 = project.setTemplate('test3', { crate: 'test2' })
assert(test3 instanceof Template)

Building

$ npm exec fadroma build CONTRACT [...CONTRACT]

Building all templates in the project:

await project.build()

Building some templates from the project:

await project.build('test1')

Checksums of compiled contracts by version are stored in the build state directory, wasm/.

Uploading

$ npm exec fadroma upload CONTRACT [...CONTRACT]

Uploading all templates in the project:

await project.upload()

Uploading some templates from the project:

await project.upload('test2')

If contract binaries are not present, the upload command will try to build them first. Every successful upload logs the transaction as a file called an upload receipt under state/$CHAIN_ID/upload.. This contains info about the upload transaction.

The UploadStore loads a collection of upload receipts and tells the Uploader if a binary has already been uploaded, so it can prevent duplicate uploads.

Deploying

$ npm exec fadroma deploy [...ARGS]

Deploying the project:

await project.deploy(/* any deploy arguments, if you've overridden the deploy procedure */)

Commencing a deployment creates a corresponding file under state/$CHAIN_ID/deploy, called a deploy receipt. As contracts are deployed as part of this deployment, their details will be appended to this file so that they can be found later.

When a deploy receipt is created, that deployment is made active. This is so you can easily find and interact with the contract you just deployed. The default deploy procedure is dependency-based, so if the deployment fails, re-running deploy should try to resume where you left off. Running deploy on a completed deployment will do nothing.

To start over, use the redeploy command:

$ npm exec fadroma redeploy [...ARGS]

await project.redeploy(/* ... */)

This will create and activate a new deployment, and deploy everything anew.

Keeping receipts of your primary mainnet/testnet deployments in your version control system will let you keep track of your project's footprint on public networks.

During development, receipts for deployments of a project are kept in a human- and VCS-friendly YAML format. When publishing an API client, you may want to include individual deployments as JSON>

await project.exportDeployment('state')

import assert from 'node:assert'
import { Template } from '@fadroma/agent'
import { tmpDir } from './fixtures/Fixtures.ts.md'
import './Project.test'