Skip to content

Commit

Permalink
wip: docs: more cleanup
Browse files Browse the repository at this point in the history
  • Loading branch information
@egasimus
egasimus committed Oct 18, 2023
1 parent e7d68d5 commit 712820e
Showing 1 changed file with 159 additions and 163 deletions.
322 changes: 159 additions & 163 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,101 @@ $ npx @hackbg/[email protected] 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:
Expand All @@ -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,
Expand All @@ -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
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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
Expand All @@ -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,
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -867,8 +865,6 @@ assert.deepEqual(
await devnet.delete()
```
---
# Configuration
|Env var|Default path|Description|
Expand Down

0 comments on commit 712820e

Please sign in to comment.