Algo Builder extension & helpers

[[TOC]]

📄 Description

All stuff which help us to develop and test Algorand Smart Contract

💬 Resources

• AlgoBuilder (official site)
• projects:
  • tomas.bert/algo-builder-scaffold
  • sandbox/smart-contracts
  • pbws/smart-contracts

📜 Docs

📁 Ext

Main directory to customize scripts

❯ AlgoBuilderScript

Basic AlgoBuilder script wrapper with some built-in extension to use out-of-box.

# scripts/my-script.ts
export default AlgoBuilderScript.of((ctx) => {
    // Do stuff with the context
});

Context [IRunScriptContext]

• runtimeEnv: RuntimeEnvExt: Extended environment RuntimeEnv (from algo-builder) with properties on NetworkConfig.
  • runtimeEnv.network.config.assets: Config custom asset ids for external networks like TestNet
  • runtimeEnv.network.config.addresses: Config addresses without private key to use
• deployerExt: IDeployerExt: The built-in extension methods from base deployer of AlgoBuilder
• addresses: IScriptAddresses: Service to read and resolve addresses from config file. ctx.addresses.getOrFail('requiredAddress')

Deployer Ext [IDeployerExt]

• algoBalanceOf: Return balance in algos.
• usdcBalanceOf: Return balance of common stable asset USDC (must be deployed before. See examples/scripts/usdc.ts)
• usdcDispenser: Dispense $USDC to account. master is the sender
• algoDispenser: Dispense $ALGO to account. master is the sender
• funder: Return a callable dispense which send the amount of usdc & algo to reach the algoLt & usdcLt configure amount. send(algoLt - account.algos)
• accountSummary: Print a summary of account in stdout
• nftsOf: Return a list of non-fungible asset which account hold.
• resolveAssetIndex: Resolve the asset index from their name or fallback to artifact folder of algobuilder.

⭐️ ❯ AlgoBuilderScriptFactory

This is the main extensible feature to customize, configure and extend custom scripts contexts with custom plugins features.

// # scripts/ext/my-custom-script-context.ts
const MyAlgoBuilderScript = AlgoBuilderScriptFactory()
  .withPlugin((ctx) => {
    return {
      ...ctx, // It's the base context IRunScriptContext
      myCoolStuff: (account: Account) => `Hello ${account.address}`
    }
  })
  // Also can add more plugins .withPlugin(otherPlugin) with context inherit

// # scripts/use.ts
export default MyAlgoBuilderScript.of((ctx) => {
    // ctx.myCoolStuff is available. And it have AUTOCOMPLETE!! 🎉
    ctx.myCoolStuff(ctx.deployer.accountsByName.get('Alice'))
    // Hello AKCX..YQJETM
})

📁 Accouts

❯ accountsBalanceReference

Show changes on the balances of accounts

const ref = await accountsBalanceReference(ctx.deployerExt).of([alice])
// transfer 1000 $ALGO to alice
ref.printDiff() // Yes!! it have colors 🤪
┌───────┬────────────────────────────────────────────────────────────┬─────────────────┬─────────────────────────┬────────┬───────────┐
│ Name  │ address                                                    │ $µALGO          │ $µALGO diff             │ $USD   │ $USD diff │
├───────┼────────────────────────────────────────────────────────────┼─────────────────┼─────────────────────────┼────────┼───────────┤
│ Alice │ FYPJZLHO67DNODLNNTUG7KQBE2ZTBOQJIXSBGSJB5DYFPARDKOZAEDCRYI │ 0 -> 1000000000 │ ↑ 1000000000 • $409.131 │ 0 -> 0 │  0        │
└───────┴────────────────────────────────────────────────────────────┴─────────────────┴─────────────────────────┴────────┴───────────┘

📁 Applications

❯ AppState

Show changes on the state (global & local) of application (smart contracts)

const state = new AppState(ctx, 'Factory')
await state.takeSnapshot()
// do something interesting with the contract
await state.printDiff()

The following will be printed on the console:

┌──────────────┬──────────────────────────────────────────────┬──────────────────────────────────────────────────────────────────────────────────────────┐
│ Key          │ Old Value                                    │ New Value                                                                                │
├──────────────┼──────────────────────────────────────────────┼──────────────────────────────────────────────────────────────────────────────────────────┤
│ FEE_ADDR     │ 5rjfIlCKqXUaKhpXWP3rfLua3Nvb3OFHUYWDqk+qfxw= │ 5rjfIlCKqXUaKhpXWP3rfLua3Nvb3OFHUYWDqk+qfxw=                                             │
├──────────────┼──────────────────────────────────────────────┼──────────────────────────────────────────────────────────────────────────────────────────┤
│ MANAGER_ADDR │ 5rjfIlCKqXUaKhpXWP3rfLua3Nvb3OFHUYWDqk+qfxw= │ 5rjfIlCKqXUaKhpXWP3rfLua3Nvb3OFHUYWDqk+qfxw=                                             │
├──────────────┼──────────────────────────────────────────────┼──────────────────────────────────────────────────────────────────────────────────────────┤
│ POFIP_HASH   │ null                                         │ hnzzWDKj8vXxjuf2+ysPFugHLyHbF4lNMTbUPRjbpQOGfPNYMqPy9fGO5/b7Kw8W6AcvIdsXiU0xNtQ9GNulAw== │
└──────────────┴──────────────────────────────────────────────┴──────────────────────────────────────────────────────────────────────────────────────────┘

tip: you can call takeSnapshot() again on the same object to update snapshot.

📁 Constants

❯ FLAT_PAY

Common object to pass on ctx.deployer.executeTx()

❯ flatPayWithMore(amountOfTransactions)

A flat pay to use on application call which do more than N inner transaction

📁 Encoder

❯ strToUInt8Array

Convert from string to Uint8Array

❯ uInt8ArrayToStr

Convert from Uint8Array to string

❯ b64ToString

Convert from encoded b64 string to string. Example b64ToString('SEVMTE8=') -> HELLO (playground)

📁 Model

Interfaces to use and type responses of AlgoClient.

📁 Terminal

❯ forPressEnter

Just a sync method which wait to press enter on the stdin. It block the execution script.

TODO

• [ ] Extend asset list for customization (see AssetName)
• [ ] Complete doc with more example and refs
• [ ] Split imports
  • import { AlgoBuilderScriptFactory } from '@travelx/algob-ext/ext/factory'
  • import { Encoder } from '@travelx/algob-ext/encoder'. Then Encoder.strToUInt8Array(..)