Skip to content

Add more tests to lib folder and link to them from docs #366

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Mar 10, 2025
Merged

Add more tests to lib folder and link to them from docs #366

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
46e059c
docs: link to tests from docs to ensure all examples execute correctly
ClemensLey Mar 9, 2025
9a944ca
Merge branch 'main' into more-work-on-docs-8
ClemensLey Mar 10, 2025
b75b228
Update README.md
ltardivo Mar 10, 2025
acc8df2
built files
ClemensLey Mar 10, 2025
6b4e942
Merge branch 'more-work-on-docs-8' of https://github.com/bitcoin-comp…
ClemensLey Mar 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
399 changes: 186 additions & 213 deletions package-lock.json
View file
Open in desktop

Large diffs are not rendered by default.

11 changes: 2 additions & 9 deletions packages/docs/Lib/Computer/broadcast.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,13 +18,6 @@ A NamamotoJS [transaction](https://github.com/bitcoin-computer/monorepo/blob/mai

If the broadcast is successful, it returns the transaction id. Otherwise, an error is thrown.

## Examples
## Example

```ts
class C extends Contract {}
const transition = { exp: `${C} new C()` }
const { tx } = await computer.encode(transition)

// Broadcast transaction
const txId = await computer.broadcast(tx)
```
:::code source="../../../lib/test/lib/computer/broadcast.test.ts" :::
31 changes: 1 addition & 30 deletions packages/docs/Lib/Computer/constructor.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,33 +45,4 @@ An instance of the `Computer` class

## Examples

```ts
import { Computer } from '@bitcoin-computer/lib'

// Connects to Bitcoin Computer Node at https://rltc.node.bitcoincomputer.io with LTC regtest
const remoteComputer = new Computer()

// Connects to local Bitcoin Computer Node on LTC regtest
const localComputer = new Computer({
chain: 'LTC',
network: 'regtest',
url: 'http://localhost:1031'
})

// Connects to remove node on BTC testnet
const bitcoinComputer = new Computer({
chain: 'BTC',
network: 'testnet',
mnemonic: 'replace this seed'
})

// More custom parameters
const customComputer = new Computer({
chain: 'LTC'
network: 'mainnet',
addressType: 'p2wpkh',
path: "m/44'/0'/0'/0",
url: 'https://my-ltc-node.com',
satPerByte: 1
})
```
:::code source="../../../lib/test/lib/computer/constructor.test.ts" :::
14 changes: 1 addition & 13 deletions packages/docs/Lib/Computer/decode.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,16 +36,4 @@ The function `decode` is the inverse of `encode` when the latter is called with

## Example

```ts
class C extends Contract {}
const computer = new Computer()
const transition = {
exp: `${C} new ${C.name}()`,
env: {},
mod: '',
}
const { tx } = await computer.encode(transition)
const decoded = await computer.decode(tx)

expect(decoded).to.deep.equal(transition)
```
:::code source="../../../lib/test/lib/computer/decode.test.ts" :::
82 changes: 2 additions & 80 deletions packages/docs/Lib/Computer/deploy.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,87 +44,9 @@ To select the module storage type pass either `multisig` or `taproot` into the p

## Examples

The first example shows how to deploy a module with module storage type `multisig`.
:::code source="../../../lib/test/lib/computer/deploy.test.ts" :::

```js
const computer = new Computer({ moduleStorageType: 'multisig' })
await computer.faucet(1730000)
const big = `x`.repeat(18262) // ~ 18KB

const rev = await computer.deploy(big)
expect(rev).to.not.equal(undefined)
```

On BTC and LTC it is possible to deploy larger modules for lower fees by using `taproot`.

```js
const computer = new Computer({ moduleStorageType: 'taproot' })
await computer.faucet(436000)
const veryBig = `x`.repeat(396000) // ~ 400KB

const rev = await computer.deploy(veryBig)
expect(rev).to.not.equal(undefined)
```

The next example shows how modules can depends on one another

```ts
// Deploy module A
const modSpecA = await computer.deploy(`export class A extends Contract {}`)

// Deploy module B that imports module B
const modSpecB = await computer.deploy(`
import { A } from '${modSpecA}'
export class B extends A {}
`)

// Use module B
const { tx } = await computer.encode({ exp: `new B()`, mod: modSpecB })
expect(tx.getId()).to.be.a.string
```

The last example shows how a string of arbitrary length can be stored using the module system. The idea is to partition a long string into constant size chunks, deploy each chunk in a separate module, and then deploy one additional module that recombined the modules for the chunks and exports their concatenation.

```js
// Inputs a long string and outputs a module specifier where it can be obtained
const store = async (s: string, n: number) => {
// Partition the long string into chunks of size n
const chunks = []
for (let i = 0; i < s.length; i += n) {
chunks.push(s.slice(i, i + n))
}

// Deploy chunks and build recombining module
let module = ''
for (let i = 0; i < s.length / n; i += 1) {
// Deploy a chunk
const mod = await computer.deploy(`export const c${i} = '${chunks[i]}'`)

// Import chunk into recombining module
module += `import { c${i} } from '${mod}'\n`
}

// Export concatenation of chunks
const cs = Array.from({ length: n + 1 }, (_, i) => `c${i}`).join(' + ')
module += `export const s = ${cs}`

// Deploy recombining module
return computer.deploy(module)
}

// Create a long string, could be hundreds MB in a real example
const longString = '0'.repeat(10)

// Store long string, you can use 18262 instead of 3 for multisig modules
// or 396000 for taproot modules
const mod = await store(longString, 3)

// Load a long string
const { s } = await computer.load(mod)
expect(s).eq(longString)
```

In the example the "recombining" module is as follows:
The last example shows how a string of arbitrary length can be stored using the module system. The idea is to partition a long string into constant size chunks, deploy each chunk in a separate module, and then deploy one additional module that recombined the modules for the chunks and exports their concatenation. In the example the "recombining" module is as follows:

```ts
import { c0 } from 'f86ec90ce2ab7367e197df1e63b45114a381d5636dc85e35dc28d721fbf0c228:0' // stores '000'
Expand Down
65 changes: 2 additions & 63 deletions packages/docs/Lib/Computer/encode.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,67 +72,6 @@ The state update effected by a Bitcoin Computer transaction is completely predic
- If the transaction is not included the state is not updated.
!!!

## Examples
## Example

The first example shows how to store a basic type

```js
import { Computer, Contract } from '@bitcoin-computer/lib'

// Encode the expression '1'
const { effect, tx } = await computer.encode({ exp: '1' })

// The effect object captures the on-chain state if the transaction is broadcast
expect(effect).deep.eq({ res: 1, env: {} })

// Broadcast the transaction
const txId = await computer.broadcast(tx)

// Synchronizing to the transaction id always returns the effect
expect(await computer.sync(txId)).deep.eq(effect)
```

The second example shows how to encode a constructor and a function call.

```js
import { Computer, Contract } from '@bitcoin-computer/lib'

// A smart contract
class Counter extends Contract {
n: number

constructor() {
super({ n: 0 })
}
inc() {
this.n += 1
}
}

// Encode a constructor cal
const { effect: e1, tx: tx1 } = await computer.encode({
exp: `${Counter} new Counter()`,
})

// Broadcast the transaction
const txId1 = await computer.broadcast(tx1)

// As above, synchronizing to a transaction id always returns the effect
expect(await computer.sync(txId1)).deep.eq(e1)

// Encode a function call
const { effect: e2, tx: tx2 } = await computer.encode({
// The expression
exp: `c.inc()`,

// The blockchain environment specifies that the value for c is stores
// the the location e1.res._rev on the blockchain
env: { c: e1.res._rev },
})

// As before we can broadcast the transaction to update the on-chain state
const txId2 = await computer.broadcast(tx2)

// The sync function reads the on-chain state
expect(await computer.sync(txId2)).deep.eq(e2)
```
:::code source="../../../lib/test/lib/computer/encode.test.ts" :::
38 changes: 2 additions & 36 deletions packages/docs/Lib/Computer/encodeCall.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,40 +41,6 @@ See [`encode`](./encode.md).

See [`encode`](./encode.md).

## Examples
## Example

```ts
// A smart contract
class Counter extends Contract {
n: number
constructor() {
super({ n: 0 })
}

inc(m) {
this.n += m
}
}

// Create a smart object from the smart contract
const computer = new Computer({ mnemonic: ... })
const counter = await computer.new(Counter)

// Encode a function call
const { tx } = await computer.encodeCall({
target: counter,
property: 'inc',
args: [1]
})

// Decode the meta data
const decoded = await computer.decode(tx)
expect(decoded).to.deep.eq({
exp: `__bc__.inc(1)`,
env: { __bc__: counter._rev },
mod: ''
})

// Broadcast the tx to commit the change
const txId = await computer.broadcast(tx)
```
:::code source="../../../lib/test/lib/computer/encode-call.test.ts" :::
28 changes: 2 additions & 26 deletions packages/docs/Lib/Computer/encodeNew.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,30 +35,6 @@ See [`encode`](./encode.md).

See [`encode`](./encode.md).

## Examples
## Example

```ts
// A smart contract
class C extends Contract {}

// Encode a constructor call
const computer = new Computer()
const { tx, effect } = await computer.encodeNew({
constructor: C,
args: [],
})

// Decode transaction
const decoded = await computer.decode(tx)
expect(decoded).to.deep.eq({
exp: `${C} new C()`,
env: {},
mod: '',
})

// Broadcast the tx to create the on-chain object
const txId = await computer.broadcast(tx)

// Synchronizing to the transaction id always returns the effect
expect(await computer.sync(txId)).deep.eq(effect)
```
:::code source="../../../lib/test/lib/computer/encode-new.test.ts" :::
40 changes: 2 additions & 38 deletions packages/docs/Lib/Computer/faucet.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,42 +26,6 @@ The utxo containing the funds.

Funds a `Computer` object on regtest. A second parameter can provide an address to fund, otherwise the calling object is funded. If the object is not configured to regtest an error is thrown.

## Examples
## Example

The first example shows how to fund the current `Computer` object.

```ts
const c = new Computer()

// Fund client side wallet
const utxo = await c.faucet(1e8)
expect(utxo).to.matchPattern({
txId: (txId) => typeof txId === 'string',
vout: (vout) => typeof vout === 'number',
height: -1,
satoshis: 1e8,
})

// Check balance
const { balance } = await c.getBalance()
expect(balance).eq(1e8)
```

The second example shows how another object can be funded.

```ts
const c1 = new Computer({ chain, network, url })
const c2 = new Computer({ chain, network, url })
await c1.faucet(1e8, c2.getAddress())
const { balance: b1 } = await c1.getBalance()
const { balance: b2 } = await c2.getBalance()
expect(b1).eq(0)
expect(b2).eq(1e8)
```

The last example shows that an error is thrown if the `Computer` object is not configured to regtest.

```ts
const c = new Computer({ network: 'testnet' })
await expect(c.faucet(1e8)).to.be.rejected
```
:::code source="../../../lib/test/lib/computer/faucet.test.ts" :::
36 changes: 2 additions & 34 deletions packages/docs/Lib/Computer/fund.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,38 +37,6 @@ UTXOs are encoded as `<transaction-id>:<output-number>`.

If the wallet does not have sufficient funds, an error is thrown.

## Examples
## Example

The first example shows how to use `fund` with a NakamotoJS transaction.

```ts
import { address, networks, Transaction } from '@bitcoin-computer/nakamotojs'
const { regtest } = networks

const tx = new Transaction()
const outputScript = address.toOutputScript('mkHS9ne12qx9pS9VojpwU5xtRd4T7X7ZUt', regtest)
tx.addOutput(outputScript, 1e7)
await computer.fund(tx)
await computer.sign(tx)
await computer.broadcast(tx)
```

The next example shows how to use `fund` with a Bitcoin Computer transaction.

```ts
// A smart contract
class C extends Contract {}

// Encode a constructor call without funding the transaction
const { tx } = await computer.encode({
exp: `${C} new ${C.name}()`,
fund: false,
})

// Another user can fund and sign
const computer2 = new Computer()
await computer2.faucet(1e8)
await computer2.fund(tx)
await computer2.sign(tx)
await computer2.broadcast(tx)
```
:::code source="../../../lib/test/lib/computer/fund.test.ts" :::
Loading