From 712820ed51fe28d5b4c7c546947270aed22d1f32 Mon Sep 17 00:00:00 2001 From: Adam Avramov Date: Wed, 18 Oct 2023 15:35:53 +0300 Subject: [PATCH] wip: docs: more cleanup --- README.md | 322 +++++++++++++++++++++++++++--------------------------- 1 file changed, 159 insertions(+), 163 deletions(-) diff --git a/README.md b/README.md index 55cd76d8c17..2b02ae6a29f 100644 --- a/README.md +++ b/README.md @@ -41,7 +41,101 @@ $ npx @hackbg/fadroma@1.5.6 create $ npm exec fadroma add ``` -## Building contracts +## Deploying a project + +```shell +# Deploy the project, or update the current deployment: +$ npm exec fadroma deploy [...ARGS] + +# Deploy everything anew: +$ npm exec fadroma redeploy [...ARGS] +``` + +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. 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 files... TODO + +### Exporting the deployment + +Deployments in YAML multi-document format are human-readable +and version control-friendly. When a list of contracts in JSON +is desired, you can use the `export` command to export a JSON +snapshot of the active deployment. + +For example, to select and export a mainnet deployment: + +```sh +npm run mainnet select NAME +npm run mainnet export [DIRECTORY] +``` + +This will create a file named `NAME_@_TIMESTAMP.json` +in the current working directory (or another specified). + +Internally, the data for the export is generated by the +`deployment.snapshot` getter: + +```typescript +// TODO +``` + +In a standard Fadroma project, where the Rust contracts +and TypeScript API client live in the same repo, by `export`ing +the latest mainnet and testnet deployments to JSON files +during the TypeScript build process, and adding them to your +API client package, you can publish an up-to-date "address book" +of your project's active contracts as part of your API client library. + +```typescript +// TODO +``` + +### Connecting to an exported deployment + +Having been deployed once, contracts may be used continously. +The `Deployment`'s `connect` method loads stored data about +the contracts in the deployment, populating the contained +`Contract` instances. + +With the above setup you can automatically connect to +your project in mainnet or testnet mode, depending on +what `Agent` you pass: + +```typescript +// TODO +``` + +Or, to connect to individual contracts from the stored deployment: + +```typescript +// TODO +``` + +### Adding custom migrations + +Migrations can be implemented as static or regular methods +of `Deployment` classes. + +```typescript +// TODO +``` + +## Building individual contracts ```shell # Build a contract from the project: @@ -52,6 +146,9 @@ $ npm exec fadroma build some-contract another-contract a-third-contract # Build all contracts in the project: $ npm exec fadroma build + +# Build contract by path: +$ npm exec fadroma /path/to/crate ``` When deploying, Fadroma automatically builds the `Contract`s specified in the deployment, @@ -75,15 +172,70 @@ corresponding to the contract crates of your project. You can Fadroma implements **reproducible compilation** of contracts. What to compile is specified using the primitives defined in [Fadroma Core](../client/README.md). -## Build CLI +## Uploading contracts ```shell -$ fadroma build CONTRACT # nop if already built -$ fadroma rebuild CONTRACT # always rebuilds +# Upload a contract: +$ npm exec fadroma upload CONTRACT [...CONTRACT] + +# Reupload a contract: +$ fadroma reupload CONTRACT # always reupload +``` + +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. + +Fadroma takes care of **uploading WASM files to get code IDs**. + +Like builds, uploads are *idempotent*: if the same code hash is +known to already be uploaded to the same chain (as represented by +an upload receipt in `state/$CHAIN/uploads/$CODE_HASH.json`, +Fadroma will skip the upload and reues the existing code ID. + +The `fadroma upload` command (available through `npm run $MODE upload` +in the default project structure) lets you access Fadroma's `Uploader` +implementation from the command line. + +## Using the local devnet + +```sh +# Deploy to devnet +$ npm run devnet deploy + +# Nuke the devnet +$ npm run devnet reset ``` - * **`CONTRACT`**: one of the contracts defined in the [project](../project/Project.spec.ts), - *or* a path to a crate assumed to contain a single contract. +Fadroma enables fully local development of projects - no remote testnet needed! +This feature is known as **Fadroma Devnet**. + +Normally, you would interact with a devnet no different than any other +`Chain`: through your `Deployment` subclass. + +When using the Fadroma CLI, `Chain` instances are provided automatically +to instances `Deployment` subclasses. + +So, when `FADROMA_CHAIN` is set to `ScrtDevnet`, your deployment will +be instantiated alongside a local devnet, ready to operate! + +As a shortcut, projects created via the Fadroma CLI contain the `devnet` +NPM script, which is an alias to `FADROMA_CHAIN=ScrtDevnet fadroma`. + +So, to deploy your project to a local devnet, you would just run: + +Fadroma Devnet includes container images based on `localsecret`, +for versions of Secret Network 1.2 to 1.9. Under the hood, the +implementation uses the library [`@hackbg/dock`](https://www.npmjs.com/package/@hackbg/dock) +to manage Docker images and containers. There is also experimental +support for Podman. + +# Scripting + +See: [Fadroma Agent API](./agent/README.md) ## Build API @@ -280,38 +432,6 @@ implement the compilation procedure for contracts. Checksums of compiled contracts by version are stored in the build state directory, `wasm/`. -## Uploading contracts - -```shell -# Upload a contract: -$ npm exec fadroma upload CONTRACT [...CONTRACT] -``` - -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. - -Fadroma takes care of **uploading WASM files to get code IDs**. - -Like builds, uploads are *idempotent*: if the same code hash is -known to already be uploaded to the same chain (as represented by -an upload receipt in `state/$CHAIN/uploads/$CODE_HASH.json`, -Fadroma will skip the upload and reues the existing code ID. - -### Upload CLI - -The `fadroma upload` command (available through `npm run $MODE upload` -in the default project structure) lets you access Fadroma's `Uploader` -implementation from the command line. - -```shell -$ fadroma upload CONTRACT # nil if same contract is already uploaded -$ fadroma reupload CONTRACT # always reupload -``` - ### Upload API The client package, `@fadroma/agent`, exposes a base `Uploader` class, @@ -351,34 +471,6 @@ await getUploader({ /* options */ }).upload({ artifact }) ## Deploying the project -```shell -$ npm exec fadroma deploy [...ARGS] -``` - -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: - -```shell -$ npm exec fadroma redeploy [...ARGS] -``` - -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 files... TODO - ### Storing and exporting deployment state By default, the list of contracts in each deployment created by Fadroma @@ -388,71 +480,6 @@ The deployment currently selected as "active" by the CLI (usually, the latest created deployment) is symlinked at `state/${CHAIN_ID}/deploy/.active.yml`. -### Exporting the deployment - -Deployments in YAML multi-document format are human-readable -and version control-friendly. When a list of contracts in JSON -is desired, you can use the `export` command to export a JSON -snapshot of the active deployment. - -For example, to select and export a mainnet deployment: - -```sh -npm run mainnet select NAME -npm run mainnet export [DIRECTORY] -``` - -This will create a file named `NAME_@_TIMESTAMP.json` -in the current working directory (or another specified). - -Internally, the data for the export is generated by the -`deployment.snapshot` getter: - -```typescript -// TODO -``` - -In a standard Fadroma project, where the Rust contracts -and TypeScript API client live in the same repo, by `export`ing -the latest mainnet and testnet deployments to JSON files -during the TypeScript build process, and adding them to your -API client package, you can publish an up-to-date "address book" -of your project's active contracts as part of your API client library. - -```typescript -// TODO -``` - -### Connecting to an exported deployment - -Having been deployed once, contracts may be used continously. -The `Deployment`'s `connect` method loads stored data about -the contracts in the deployment, populating the contained -`Contract` instances. - -With the above setup you can automatically connect to -your project in mainnet or testnet mode, depending on -what `Agent` you pass: - -```typescript -// TODO -``` - -Or, to connect to individual contracts from the stored deployment: - -```typescript -// TODO -``` - -### Adding custom migrations - -Migrations can be implemented as static or regular methods -of `Deployment` classes. - -```typescript -// TODO -``` - ## Template The `Template` class represents a smart contract's source, compilation, @@ -584,36 +611,7 @@ await deployment.a.built await deployment.a.build() ``` -## Devnet - -Fadroma enables fully local development of projects - no remote testnet needed! -This feature is known as **Fadroma Devnet**. - -Normally, you would interact with a devnet no different than any other -`Chain`: through your `Deployment` subclass. - -When using the Fadroma CLI, `Chain` instances are provided automatically -to instances `Deployment` subclasses. - -So, when `FADROMA_CHAIN` is set to `ScrtDevnet`, your deployment will -be instantiated alongside a local devnet, ready to operate! - -As a shortcut, projects created via the Fadroma CLI contain the `devnet` -NPM script, which is an alias to `FADROMA_CHAIN=ScrtDevnet fadroma`. - -So, to deploy your project to a local devnet, you would just run: - -```sh -$ npm run devnet deploy -``` - -## Advanced usage - -Fadroma Devnet includes container images based on `localsecret`, -for versions of Secret Network 1.2 to 1.9. Under the hood, the -implementation uses the library [`@hackbg/dock`](https://www.npmjs.com/package/@hackbg/dock) -to manage Docker images and containers. There is also experimental -support for Podman. +## Devnet API ### Creating the devnet @@ -867,8 +865,6 @@ assert.deepEqual( await devnet.delete() ``` ---- - # Configuration |Env var|Default path|Description|