From 0218de43ce12e36fdd1d4402984f4af8f1ac5f68 Mon Sep 17 00:00:00 2001 From: Adam Avramov Date: Wed, 18 Oct 2023 15:57:13 +0300 Subject: [PATCH] docs: populate state section --- README.md | 124 ++++++++++++++++++++++++------------------------------ 1 file changed, 55 insertions(+), 69 deletions(-) diff --git a/README.md b/README.md index 41803f98e89..b59953989bf 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,7 @@ for a guide to deploying your Rust contracts using the Fadroma TypeScript packag # Getting started -## Creating a project and defining contracts +## Create a project and define contracts ```shell # Create a project: @@ -41,7 +41,7 @@ $ npx @hackbg/fadroma@1.5.6 create $ npm exec fadroma add ``` -## Deploying your project +## Deploy your project ```shell # Deploy the project, or update the current deployment: @@ -49,44 +49,28 @@ $ npm exec fadroma deploy [...ARGS] # Deploy everything anew: $ npm exec fadroma redeploy [...ARGS] + +# Select another deployment +$ npm exec fadroma select my-deployment + +# Export deployment state to ./my-deployment_@_timestamp.json +$ npm exec fadroma export + +# Export deployment state to ./some-directory/my-deployment_@_timestamp.json +$ npm exec fadroma export ./some-directory ``` -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. +## Connect to a deployed project 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 +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: @@ -105,8 +89,6 @@ of your project's active contracts as part of your API client library. // 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 @@ -126,7 +108,7 @@ Or, to connect to individual contracts from the stored deployment: // TODO ``` -### Adding custom migrations +## Define custom migrations in a deployment Migrations can be implemented as static or regular methods of `Deployment` classes. @@ -135,7 +117,7 @@ of `Deployment` classes. // TODO ``` -## Building individual contracts +## Build individual contracts ```shell # Build a contract from the project: @@ -172,7 +154,7 @@ 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). -## Uploading individual contracts +## Upload individual contracts ```shell # Upload a contract: @@ -182,25 +164,12 @@ $ npm exec fadroma upload CONTRACT [...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 +Fadroma takes care of **uploading WASM files to get code IDs**. 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. +Fadroma will skip the upload and reuse 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 +## Deploying to the local devnet ```sh # Deploy to devnet @@ -254,16 +223,16 @@ support for Podman. |env var|type|description| |-|-|-| -|**`FADROMA_BUILD_VERBOSE`**|flag|more log output +|**`FADROMA_ARTIFACTS`**|path|project artifact cache +|**`FADROMA_BUILD_DOCKERFILE`**|path to dockerfile|dockerfile to build image if missing +|**`FADROMA_BUILD_IMAGE`**|docker image tag|image to run +|**`FADROMA_BUILD_PODMAN`**|flag|whether to use podman instead of docker |**`FADROMA_BUILD_QUIET`**|flag|less log output -|**`FADROMA_BUILD_SCRIPT`**|path to script|build implementation |**`FADROMA_BUILD_RAW`**|flag|run the build script in the current environment instead of container +|**`FADROMA_BUILD_SCRIPT`**|path to script|build implementation +|**`FADROMA_BUILD_VERBOSE`**|flag|more log output |**`FADROMA_DOCKER`**|host:port or socket|non-default docker socket address -|**`FADROMA_BUILD_IMAGE`**|docker image tag|image to run -|**`FADROMA_BUILD_DOCKERFILE`**|path to dockerfile|dockerfile to build image if missing -|**`FADROMA_BUILD_PODMAN`**|flag|whether to use podman instead of docker |**`FADROMA_PROJECT`**|path|root of project -|**`FADROMA_ARTIFACTS`**|path|project artifact cache |**`FADROMA_REBUILD`**|flag|builds always run, artifact cache is ignored # State @@ -275,10 +244,38 @@ for a corresponding pre-existing build and reuses it if present. Setting `FADROMA_REBUILD` disables build caching. -## Upload cache +## Upload receipts + +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. ## Deploy receipts +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. + +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 + +By default, the list of contracts in each deployment created by Fadroma +is stored in `state/${CHAIN_ID}/deploy/${DEPLOYMENT}.yml`. + +The deployment currently selected as "active" by the CLI +(usually, the latest created deployment) is symlinked at +`state/${CHAIN_ID}/deploy/.active.yml`. + ## Devnet state Each **devnet** is a stateful local instance of a chain node @@ -557,17 +554,6 @@ import { getUploader } from '@hackbg/fadroma' await getUploader({ /* options */ }).upload({ artifact }) ``` -## Deploying the project - -### Storing and exporting deployment state - -By default, the list of contracts in each deployment created by Fadroma -is stored in `state/${CHAIN_ID}/deploy/${DEPLOYMENT}.yml`. - -The deployment currently selected as "active" by the CLI -(usually, the latest created deployment) is symlinked at -`state/${CHAIN_ID}/deploy/.active.yml`. - ## Devnet API ### Creating the devnet