Skip to content

Commit

Permalink
wip: docs: move TS stuff to test suite
Browse files Browse the repository at this point in the history
  • Loading branch information
@egasimus
egasimus committed Oct 18, 2023
1 parent e8307bc commit 752214d
Show file tree
Hide file tree
Showing 2 changed files with 120 additions and 116 deletions.
123 changes: 12 additions & 111 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -131,10 +131,7 @@ Internally, the data for the export is generated by the
`deployment.snapshot` getter:
```typescript
assert.deepEqual(
Object.keys(deployment.snapshot.contracts),
['kv1', 'kv2']
)
// TODO
```
In a standard Fadroma project, where the Rust contracts
Expand All @@ -145,29 +142,7 @@ 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
// in your project's api.ts:
import { Deployment } from '@fadroma/agent'
// you would load snapshots as JSON, e.g.:
// const testnet = await (await fetch('./testnet_v4.json')).json()
export const mainnet = deployment.snapshot
export const testnet = deployment.snapshot
// and create instances of your deployment with preloaded
// "address books" of contracts. for example here we restore
// a different snapshot depending on whether we're passed a
// mainnet or testnet connection.
class DeploymentC extends Deployment {
kv1 = this.contract({ crate: 'examples/kv', name: 'kv1', initMsg: {} })
kv2 = this.contract({ crate: 'examples/kv', name: 'kv2', initMsg: {} })
static connect = (agent: Agent) => {
if (agent?.chain?.isMainnet) return new this({ ...mainnet, agent })
if (agent?.chain?.isTestnet) return new this({ ...testnet, agent })
return new this({ agent })
}
}
// TODO
```
### Connecting to an exported deployment
Expand All @@ -182,27 +157,13 @@ your project in mainnet or testnet mode, depending on
what `Agent` you pass:
```typescript
const mainnetAgent = { chain: { isMainnet: true } } // mock
const testnetAgent = { chain: { isTestnet: true } } // mock
const onMainnet = DeploymentC.connect(mainnetAgent)
const onTestnet = DeploymentC.connect(testnetAgent)
assert(onMainnet.isMainnet)
assert(onTestnet.isTestnet)
assert.deepEqual(Object.keys(onMainnet.contracts), ['kv1', 'kv2'])
assert.deepEqual(Object.keys(onTestnet.contracts), ['kv1', 'kv2'])
// TODO
```
Or, to connect to individual contracts from the stored deployment:
```typescript
const kv1 = DeploymentC.connect(mainnetAgent).kv1.expect()
assert(kv1 instanceof Client)
const kv2 = DeploymentC.connect(testnetAgent).kv2.expect()
assert(kv2 instanceof Client)
// TODO
```
### Adding custom migrations
Expand All @@ -211,22 +172,7 @@ Migrations can be implemented as static or regular methods
of `Deployment` classes.
```typescript
// in your project's api.ts:
import { Deployment } from '@fadroma/agent'
class DeploymentD extends DeploymentC {
kv3 = this.contract({ crate: 'examples/kv', name: 'kv3', initMsg: {} })
// simplest client-side migration is to just instantiate
// a new deployment with the data from the old deployment.
static upgrade = (previous: DeploymentC) =>
new this({ ...previous })
}
// simplest chain-side migration is to just call default deploy,
// which should reuse kv1 and kv2 and only deploy kv3.
deployment = await DeploymentD.upgrade(deployment).deploy()
// TODO
```
## Template
Expand All @@ -245,40 +191,13 @@ an `address`.
The `deployment.template` method adds a `Template` to the `Deployment`.
```typescript
class Deployment4 extends Deployment {
t = this.template({ crate: 'examples/kv' })
a = this.t.instance({ name: 'a', initMsg: {} })
b = this.t.instances([
{name:'b1',initMsg:{}},
{name:'b2',initMsg:{}},
{name:'b3',initMsg:{}}
])
c = this.t.instances({
c1:{name:'c1',initMsg:{}},
c2:{name:'c2',initMsg:{}},
c3:{name:'c3',initMsg:{}}
})
}
// TODO
```
You can pass either an array or an object to `template.instances`.
```typescript
deployment = await getDeployment(Deployment4).deploy()
assert(deployment.t instanceof Template)
assert([
deployment.a,
...Object.values(deployment.b)
...Object.values(deployment.c)
].every(
c=>(c instanceof Contract) && (c.expect() instanceof Client)
))
// TODO
```
### Building from source code
Expand All @@ -288,32 +207,24 @@ When obtaining instances from a `Deployment`, the `builder` property
is provided automatically from `deployment.builder`.
```typescript
import { Builder } from '@fadroma/agent'
assert(deployment.t.builder instanceof Builder)
assert.equal(deployment.t.builder, deployment.builder)
// TODO
```
You can build a `Template` (or its subclass, `Contract`) by awaiting the
`built` property or the return value of the `build()` method.
```typescript
await deployment.t.built
// -or-
await deployment.t.build()
// TODO
```
See [the **build guide**](./build.html) for more info.
### Uploading binaries
To upload, the `uploader` property must be set to a valid `Uploader`.
When obtaining instances from a `Deployment`, the `uploader` property
is provided automatically from `deployment.uploader`.
```typescript
import { Uploader } from '@fadroma/agent'
assert(deployment.t.uploader instanceof Uploader)
assert.equal(deployment.t.uploader, deployment.uploader)
// TODO
```
You can upload a `Template` (or its subclass, `Contract`) by awaiting the
Expand All @@ -323,13 +234,9 @@ If a WASM binary is not present (`template.artifact` is empty),
but a source and a builder are present, this will also try to build the contract.
```typescript
await deployment.t.uploaded
// -or-
await deployment.t.upload()
// TODO
```
See [the **upload guide**](./upload.html) for more info.
## Contract
The `Contract` class describes an individual smart contract instance and uniquely identifies it
Expand Down Expand Up @@ -399,13 +306,7 @@ await deployment.a.built
await deployment.a.build()
```
```typescript
import './Deploy.test.ts'
```
---
# Fadroma Guide: Devnet
## Fadroma Guide: Devnet
Fadroma enables fully local development of projects - no remote testnet needed!
This feature is known as **Fadroma Devnet**.
Expand Down
113 changes: 108 additions & 5 deletions fadroma.test.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -76,9 +76,112 @@ export async function testProject () {
await project.exportDeployment('state')
}

export async function testDeploy () {
import { Deployment, Template, Contract, Client } from '@fadroma/agent'
let deployment: Deployment
let template: Template
let contract: Contract
export async function testDeployment () {
assert.deepEqual(
Object.keys(deployment.snapshot.contracts),
['kv1', 'kv2']
)
// in your project's api.ts:

import { Deployment } from '@fadroma/agent'

// you would load snapshots as JSON, e.g.:
// const testnet = await (await fetch('./testnet_v4.json')).json()
export const mainnet = deployment.snapshot
export const testnet = deployment.snapshot

// and create instances of your deployment with preloaded
// "address books" of contracts. for example here we restore
// a different snapshot depending on whether we're passed a
// mainnet or testnet connection.
class DeploymentC extends Deployment {
kv1 = this.contract({ crate: 'examples/kv', name: 'kv1', initMsg: {} })
kv2 = this.contract({ crate: 'examples/kv', name: 'kv2', initMsg: {} })

static connect = (agent: Agent) => {
if (agent?.chain?.isMainnet) return new this({ ...mainnet, agent })
if (agent?.chain?.isTestnet) return new this({ ...testnet, agent })
return new this({ agent })
}
}
const mainnetAgent = { chain: { isMainnet: true } } // mock
const testnetAgent = { chain: { isTestnet: true } } // mock

const onMainnet = DeploymentC.connect(mainnetAgent)

const onTestnet = DeploymentC.connect(testnetAgent)

assert(onMainnet.isMainnet)
assert(onTestnet.isTestnet)
assert.deepEqual(Object.keys(onMainnet.contracts), ['kv1', 'kv2'])
assert.deepEqual(Object.keys(onTestnet.contracts), ['kv1', 'kv2'])

const kv1 = DeploymentC.connect(mainnetAgent).kv1.expect()
assert(kv1 instanceof Client)

const kv2 = DeploymentC.connect(testnetAgent).kv2.expect()
assert(kv2 instanceof Client)
// in your project's api.ts:

import { Deployment } from '@fadroma/agent'

class DeploymentD extends DeploymentC {
kv3 = this.contract({ crate: 'examples/kv', name: 'kv3', initMsg: {} })

// simplest client-side migration is to just instantiate
// a new deployment with the data from the old deployment.
static upgrade = (previous: DeploymentC) =>
new this({ ...previous })
}

// simplest chain-side migration is to just call default deploy,
// which should reuse kv1 and kv2 and only deploy kv3.
deployment = await DeploymentD.upgrade(deployment).deploy()
class Deployment4 extends Deployment {

t = this.template({ crate: 'examples/kv' })

a = this.t.instance({ name: 'a', initMsg: {} })

b = this.t.instances([
{name:'b1',initMsg:{}},
{name:'b2',initMsg:{}},
{name:'b3',initMsg:{}}
])

c = this.t.instances({
c1:{name:'c1',initMsg:{}},
c2:{name:'c2',initMsg:{}},
c3:{name:'c3',initMsg:{}}
})

}
deployment = await getDeployment(Deployment4).deploy()
assert(deployment.t instanceof Template)

assert([
deployment.a,
...Object.values(deployment.b)
...Object.values(deployment.c)
].every(
c=>(c instanceof Contract) && (c.expect() instanceof Client)
))
}

export async function testBuild () {
import { Builder } from '@fadroma/agent'
assert(deployment.t.builder instanceof Builder)
assert.equal(deployment.t.builder, deployment.builder)
await deployment.t.built
// -or-
await deployment.t.build()
}

export async function testUpload () {
import { Uploader } from '@fadroma/agent'
assert(deployment.t.uploader instanceof Uploader)
assert.equal(deployment.t.uploader, deployment.uploader)
await deployment.t.uploaded
// -or-
await deployment.t.upload()
}

0 comments on commit 752214d

Please sign in to comment.