Skip to content

Commit

Permalink
docs: populate state section
Browse files Browse the repository at this point in the history
  • Loading branch information
@egasimus
egasimus committed Oct 18, 2023
1 parent bf51007 commit 0218de4
Showing 1 changed file with 55 additions and 69 deletions.
124 changes: 55 additions & 69 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -41,52 +41,36 @@ $ npx @hackbg/[email protected] create
$ npm exec fadroma add
```

## Deploying your project
## Deploy your project

```shell
# Deploy the project, or update the current deployment:
$ 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:
Expand All @@ -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
Expand All @@ -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.
Expand All @@ -135,7 +117,7 @@ of `Deployment` classes.
// TODO
```
## Building individual contracts
## Build individual contracts
```shell
# Build a contract from the project:
Expand Down Expand Up @@ -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:
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down

0 comments on commit 0218de4

Please sign in to comment.