aa-testkit

Instant Obyte devnet network set up and testing

Quick Start

To quick start with autonomous agent development run the following command:

# requires npm 5.2+ installed
npx create-aa my-agent

This command will prepare the project and the environment from template for AA development.

Also check the VScode extension for AA development and testing

Usage

// import test framework
const { Testkit } = require('aa-testkit')
const { Network } = Testkit()

// spin up new devnet
const network = await Network.create().run()
const genesis = await network.getGenesisNode().ready()

// create new wallet and send some bytes from rich genesis node
const wallet = await network.newHeadlessWallet().ready()
const walletAddress = await wallet.getAddress()
const { unit } = await genesis.sendBytes({ toAddress: walletAddress, amount: 1000000 })
// and wait for witnessing
await network.witnessUntilStable(unit)

// get wallet balance
const walletBalance = await wallet.getBalance()

Note: Node internal logs with usefull information can be found in testdata/runid-{runId}/{nodeId}/.config/{nodeType}/log.txt

Testkit API

Defines how to import and configure aa-testkit module

`Testkit(config)` `: { Network, Nodes }`

Testkit constructor function. Helps to configure network defaults

Parameters

config - network defaults configuration object

Property	Type	Required	Default	Description
TESTDATA_DIR	String	false	`node_modules/aa-testkit/testdata`	Absolute path to `testdata` directory
NETWORK_PORT	Number	false	6611	Defines port, the network will be run on
WALLETS_ARE_SINGLE_ADDRESS	Boolean	false	true	Defines if HeadlessWallet nodes are single address by default

Example

const { Testkit } = require('aa-testkit')
const path = require('path')

const { Network } = Testkit({
  // should be absolute path
  TESTDATA_DIR: path.join(__dirname, '../testdata'),
  NETWORK_PORT: 5000,
})

Alternatively, if you are using node-config you can configure Testkit as aa-testkit submodule

Configuration with node-config

// config/default.js
const path = require('path')

module.exports = {
  'aa-testkit': {
    TESTDATA_DIR: path.join(__dirname, '../testdata'),
    NETWORK_PORT: 6611,
  },
}

// then you can import `aa-testkit` and `config` variables will be used
const { Testkit } = require('aa-testkit')
const { Network } = Testkit()

Network API

Primary way to operate with network. Contains common functions for network management

`Network.create(genesisParams, hubParams)` `: <network>`

Creates new devnet network from the scratch. .run() should be called after .create() for network to start. Starts GenesisNode and ObyteHub node, the required minimum for network to operate. GenesisNode also provides functions of network witness. GenesisNode has a lot (1e15 - 821) of Bytes on its account.

Parameters

genesisParams - object passed to GenesisNode constructor to override default values. See GenesisNode Nodes API section.

hubParams - object passed to ObyteHub constructor to override default values. See ObyteHub Nodes API section.

Example

const { Testkit } = require('aa-testkit')
const { Network } = Testkit()

const network = await Network.create().run()

`Network.create.with`

A set of helpers for running network with some preconditions e.g. wallets running with balances, agents deployed and assets created.

`.with.wallet({ walletName: balances }[, mnemonic: String])`

Create a wallet with some bytes or assets balances on its account.

walletName - a name for the wallet; the wallet node will be available as network.wallet.walletName

balances - initial balances of this wallet. Could be a number for the Bytes balance or object

mnemonic - optional field. Allows to specify mnemonic of the wallet

{
  base: 1e9,
  someasset: 1000, // asset keys are defined in `.with.asset` call
  asset2: 1e6
}

with.wallet can be chained to create multiple wallets

`.with.agent({ agentName: source })`

Create an agent. Multiple agents creation is supported

agentName - a name for the agent; agent address will be avaliable in network.agents.agentName

source - string with agent or absolute path to the file with agent or anything supported by wallet.deployAgent(source)

`.with.asset({ assetName: assetDefinition })`

Create an asset. Multiple assets creation is supported

assetName - a name for the asset; asset unit hash will be avaliable avaliable in network.asset.assetName

assetDefinition - object containing asset definition. Refer to wallet.createAsset(assetDefinition) for example. Any required field of the definition can be omitted, omitted fields will be replaced with default values

{
  is_private: false,
  is_transferrable: true,
  auto_destroy: false,
  issued_by_definer_only: true,
  cosigned_by_definer: false,
  spender_attested: false,
  fixed_denominations: false,
}

`.with.numberOfWitnesses(number)`

Specify number of witnesses defined in the network

number - number of witnesses. Default is 3

`.with.custom(MyNode, { nodeName: balances })`

Create custom node with balances

MyNode - class with implementation of Custom.Node

nodeName - name for node to be available via network.custom.nodeName

balances - same as for .with.wallet

`.network.deployer`

Asset or agents deployed with with helpers are deployed with extra node called deployer. Deployer node will be avaliable as network.deployer only if with.agent or with.asset was used

Example

const { Testkit } = require('aa-testkit')
const { Network } = Testkit()

const network = await Network.create()
  .with.agent({ bouncer: path.join(__dirname, './files/bouncer.oscript') })
  .with.asset({ someasset: {} })
  .with.wallet({ alice: 1e6 })
  .with.wallet({ bob: { base: 1000 } })
  .with.wallet({ eva: { base: 1e9, someasset: 1e9 } })
  .with.wallet({ mark: { someasset: 1e10 } })
  .run()

// wallets are avaliable like this
const balances = await network.wallet.alice.getBalance()
const { unit, error } = await network.wallet.bob.sendBytes({ toAddress: await network.wallet.bob.getAddress(), amount: 100e9 })
const { unitObj } = await network.wallet.eva.getUnitInfo({ unit: unit })
const mark = network.wallet.mark

// agent address
const agentAddress = network.agent.bouncer

// asset unit hash
const asset = network.asset.someasset

// deployer node
const deployer = network.deployer

Also refer to withFeature test code example

`.with.explorer({ port })`

Start network with the Obyte Explorer node

port - port to run Obyte Explorer on. Default 8080

`network.getGenesisNode()` `: <GenesisNode>`

Returns GenesisNode of this network

Example

const { Testkit } = require('aa-testkit')
const { Network } = Testkit()

const network = await Network.create().run()
// calling `.ready()` assures that node have started at this point
const genesis = await network.getGenesisNode().ready()

`network.getHub()` `: <ObyteHub>`

Returns ObyteHub of this network

Example

const { Testkit } = require('aa-testkit')
const { Network } = Testkit()

const network = await Network.create().run()
// calling `.ready()` assures that node have started at this point
const hub = await network.getHub().ready()

`network.newHeadlessWallet(params)` `: <HeadlessWallet>`

Creates and starts new HeadlessWallet node in network.

Parameters

params - object passed to HeadlessWallet constructor to override default values. See HeadlessWallet Nodes API section.

Example

const { Testkit } = require('aa-testkit')
const { Network } = Testkit()

const network = await Network.create().run()
const genesis = await network.getGenesisNode().ready()
const wallet = await network.newHeadlessWallet().ready()

`network.newObyteExplorer(params)` `: <ObyteExplorer>`

Creates and starts new ObyteExplorer node in network.

Parameters

params - object passed to ObyteExplorer constructor to override default values. See ObyteExplorer Nodes API section.

Example

const { Testkit } = require('aa-testkit')
const { Network } = Testkit()

const network = await Network.create().run()
const genesis = await network.getGenesisNode().ready()

const explorer = await network.newObyteExplorer().ready()

`network.newCustomNode(MyNode)` `: <Custom.Node>`

Creates and starts new Custom.Node node in network.

Parameters

MyNode - implementation of Custom.Node

Example

const MyNode = require('./MyNode')
const custom = await network.newCustomNode(MyNode).ready()

`network.sync()` `: Promise<>`

Wait for MCI on every node to be synchronized. Returns Promise that will be resolved when MCI on every node become identical.

`network.witnessUntilStable(unit)` `: Promise<>`

Post witnesse until unit becomes stable. Promise will be resolved when unit becomes stable.

Parameters

unit: String - wait for stabilization of this unit

Example

const { Testkit } = require('aa-testkit')
const { Network } = Testkit()

const network = await Network.create().run()
const genesis = await network.getGenesisNode().ready()

// create wallet and send bytes to it
const wallet = await network.newHeadlessWallet().ready()
const walletAddress = await wallet.getAddress()
const { unit } = await genesis.sendBytes({ toAddress: walletAddress, amount: 1000000 })
// witness last transaction
await network.witnessUntilStable(unit)

`network.witnessUntilStableOnNode(node, unit)` `: Promise<>`

Post witness transactions until unit becomes stable on node node.

Parameters

node: Node - wait for stabilization on this node unit: String - wait for stabilization of this unit

Example

const { Testkit } = require('aa-testkit')
const { Network } = Testkit()

const network = await Network.create().run()
const genesis = await network.getGenesisNode().ready()

const wallet = await network.newHeadlessWallet().ready()
const address = await wallet.getAddress()

const { unit } = await genesis.sendBytes({ toAddress: address, amount: 100000 })
await network.witnessUntilStableOnNode(wallet, unit)

`network.getAaResponseToUnit(unit)` `: Promise<{ response }>`

Retrieve autonomous agent execution response from unit. The method will make the network post witnesses until a response is received. Waits for the response on genesis node. If the unit unit triggers several AAs at the same time, the behavior of this function is undefined, use getAaResponseToUnitByAA(unit, aa) instead.

Returns Promise that resolves to { response } where response is the object of agent response

Parameters

unit : String - unit of aa execution to retrieve response from

Example

See Agent AA response test example

Response Object example

{
  mci: 13,
  trigger_address: 'VL53Z3AQWQ7AX4QKFBA42B3YPY3UYIGK',
  trigger_initial_address: 'VL53Z3AQWQ7AX4QKFBA42B3YPY3UYIGK',
  trigger_unit: 'N9PI6hN+vmVMkmXMh58pFZErGt638Fwr6yhLQw3g3HA=',
  aa_address: 'WWHEN5NDHBI2UF4CLJ7LQ7VAW2QELMD7',
  bounced: false,
  response_unit: 'm2vasHgREngt/7f0y4g2d42A8Ih+A9iu5dBWGU5pnWg=',
  objResponseUnit: {
    version: '2.0dev',
    alt: '3',
    timestamp: 1574171283,
    messages: [[Object], [Object]],
    authors: [[Object]],
    last_ball_unit: 'myDMlLHavXhVF+IMkXS6ir/GkXFASXplaNzDCpsV/kA=',
    last_ball: 'jfh9QBcZVXsWE+Q5pstRQO1STO7gfngx9pLIVAxhsUM=',
    witness_list_unit: 'rC7dZW1x3OCw8Bh+6urKN5OB0rnsmNeNy6Exz3n+rZI=',
    parent_units: ['N9PI6hN+vmVMkmXMh58pFZErGt638Fwr6yhLQw3g3HA='],
    headers_commission: 267,
    payload_commission: 259,
    unit: 'm2vasHgREngt/7f0y4g2d42A8Ih+A9iu5dBWGU5pnWg=',
  },
  response: {
    responseVars:
      { team_asset: 'm2vasHgREngt/7f0y4g2d42A8Ih+A9iu5dBWGU5pnWg=' },
  },
  updatedStateVars: {
    WWHEN5NDHBI2UF4CLJ7LQ7VAW2QELMD7: {
      team_VL53Z3AQWQ7AX4QKFBA42B3YPY3UYIGK_founder_tax: [Object],
      team_VL53Z3AQWQ7AX4QKFBA42B3YPY3UYIGK_asset: [Object],
    },
  },
}

`getAaResponseToUnitOnNode(node, unit)` `: Promise<{ response }>`

Same as network.getAaResponseToUnit but with the parameter to specify a node

Returns Promise that resolves to { response } where response is the object of agent response

Parameters

node : Node - node to wait AA response on

unit : String - unit of aa execution to retrieve response from

`getAaResponseToUnitByAA(unit, aa)` `: Promise<{ response }>`

Same as network.getAaResponseToUnit but with a parameter to specify an AA whose response to get. Use it when the triggering transaction triggers several AAs.

Returns Promise that resolves to { response } where response is the object of agent response

Parameters

unit : String - unit of aa execution to retrieve response from

aa : String - address of the AA whose response to get

`getAaResponseToUnitByAAOnNode(node, unit, aa)` `: Promise<{ response }>`

Same as network.getAaResponseToUnit but with parameters to specify a node to retrieve information from and an AA whose response to get.

Returns Promise that resolves to { response } where response is the object of agent response

Parameters

node : Node - node to wait AA response on

unit : String - unit of aa execution to retrieve response from

aa : String - address of the AA whose response to get

`network.timetravel({ to, shift })` `: Promise<{ error: String, timestamp: Number }>`

Allows to set the current network time in the future. This can be helpful for testing time-dependent AA.

Note: timetravel should be used only after every node has been started. Running a node after timetravel can lead to network inconsistency.

Note: If traveling when time is frozen, the time will be frozen to the new traveled time

Returns Promise that resolves to { error, timestamp } after timetravel is done. timestamp is current timestamp on network after timetravel. error will be null if timetravel call was successfull

Parameters

to - new time of the network. Can be either a timestamp or a string in the valid format of Date() function

shift - an offset for a current network time. You can pass a Number for a milliseconds or a String in format %number%duration

%duration	Example	Result
's'	'5s'	shift in 5 seconds
'm'	'10m'	shift in 10 minutes
'h'	'24h'	shift in 24 hours
'd'	'365d'	shift in 365 days

If both of to and shift are present, to will be used

Example

const { Testkit } = require('aa-testkit')
const { Network } = Testkit()

const network = await Network.create().run()
const genesis = await network.getGenesisNode().ready()

const { error } = await network.timetravel({ to: '2050-01-01' })

Also check in Test Examples

`network.timefreeze()` `: Promise<{ error: string }>`

Allows to stop time running on the nodes in the network. This can be helpful for testing time-dependent AA.

Note: timefreeze should be used only after every node has been started. Running a node after timefreeze call can lead to network inconsistency.

Note: If traveling when time is frozen, the time will be frozen to the new traveled time

Returns Promise that resolves to { error } after timefreeze is done. error will be null if timefreeze was successfull

`network.timerun()` `: Promise<{ error: string }>`

This function resumes time running on the nodes in the network. Time resumes from the last time-traveled position.

Returns Promise that resolves to { error } after timerun is done. error will be null if timerun was successfull

`network.stop()` `: Promise<>`

Send the command to every node to stop the process.

Example

const { Testkit } = require('aa-testkit')
const { Network } = Testkit()

const network = await Network.create().run()
const genesis = await network.getGenesisNode().ready()
const wallet = await network.newHeadlessWallet().ready()

// wait until every node exits
await network.stop()

Nodes API

Section describes all aspects supported by nodes. This aspects includes constructor parameters, methods and events

Note: Most of node constructor parameters are not required when using Network API

Any node can be created directly without using Network API. Although, it is not common but it allows you to create fully custom network

Every node runs inside its own child process. Main process sends commands to nodes and receives messages from them via Node.js IPC.

Creating nodes manually

const { Testkit } = require('aa-testkit')
const path = require('path')

const testdata = path.join(__dirname, '../testdata')
const { Nodes } = Testkit({
  TESTDATA_DIR: testdata,
})
const rundir = path.join(testdata, 'custom')
const genesisNode = new Nodes.GenesisNode({
  rundir,
  id: 'genesis-node',
})
const { genesisUnit, genesisAddress } = await genesisNode.createGenesis()

// Hub will be created and started after genesis node because hub needs to know genesis unit and its main witness(genesis node)
const hub = new Nodes.ObyteHub({
  rundir: rundir,
  genesisUnit: genesisUnit,
  initialWitnesses: [genesisAddress],
  id: 'obyte-hub',
})

await genesisNode.ready()
await hub.ready()
// wait for genesis node to login to hub node
await genesisNode.loginToHub()

const wallet = new Nodes.HeadlessWallet({
  rundir: rundir,
  genesisUnit: genesisUnit,
  id: 'headless-wallet-1',
})
await wallet.ready()

const walletAddress = await wallet.getAddress()

// do something usefull here ...

await genesisNode.stop()
await wallet.stop()
await hub.stop()

Common node methods

Methods described in this section are applicable for any node

`node.ready()` `: Promise<>`

Returns Promise that resolves when node child will be ready to operate

`node.stop()` `: Promise<>`

Returns Promise that resolves when node child exited its process

`node.waitForNewJoint()` `: Promise<joint>`

Returns Promise that resolves to joint object when node child receives and validates new joint

Joint object example

{
  unit:
  {
    version: '2.0dev',
    alt: '3',
    messages: [ [Object] ],
    authors: [ [Object] ],
    timestamp: 1576682858,
    parent_units: [ 'A7QwnTCN2kKspj8Mfs5MQGkM9oMoaMvZmIQzq3VWZEM=' ],
    last_ball: '0hlnU+5lXnT5s8j22DJQ6OYPdRI3ymqJ1JG0zvcJ9OE=',
    last_ball_unit: 'jrEkfzJMZ6mSituUJBN/YOjO56rkopZPT04JGfs6BSo=',
    witness_list_unit: 'kTGo2ttgTUkj8bjF6lWKL+afeJm3OIjO+wUJBe0a0fc=',
    headers_commission: 402,
    payload_commission: 197,
    unit: 'ZvGvEjo7/nZ5P70XAGzafqcjqeeww/1mT6zi/fVTfUk='
  }
}

`node.waitForUnit(unit)` `: Promise<>`

Returns Promise that resolves when node receives joint with specified unit id

`node.waitForUnits(units)` `: Promise<>`

Returns Promise that resolves when node receives joint for every unit id in units array

units - array of unit ids

`node.timetravel({ to, shift })` `: Promise<{ error: String, timestamp: Number }>`

Send the command to node child to change its time. This can be helpful for testing time-dependent AA.

Note: Timetravel should be used only after every node has been started. Running a node after timetravel can lead to network inconsistency.

Returns Promise that resolves to { error, timestamp } when node child receives mci_became_stable event. timestamp is current timestamp on network after timetravel. error will be null if timetravel was successfull

Parameters

to - new time of the network. Can be either a timestamp or a string in the valid format of Date() function

shift - an offset for a current network time. You can pass a Number for a milliseconds or a String in format %number%duration

%duration	Example	Result
's'	'5s'	shift in 5 seconds
'm'	'10m'	shift in 10 minutes
'h'	'24h'	shift in 24 hours
'd'	'365d'	shift in 365 days

If both of to and shift are present, to will be used

`node.getTime()` `: Promise<{ time: number }>`

Receive details about unit from node. Uses ocore/storage.readJoint method

Promise resolves as { time } object and time is in milliseconds

`node.getLastMCI()` `: Promise<mci: number>`

Get node last Main Chain Index

Promise resolves as mci

`node.getUnitInfo({ unit })` `: Promise<{ unitObj, error }>`

Receive details about unit from node. Uses ocore/storage.readJoint method

Promise resolves as { unitObj, error }. Error will be null if everything is ok

Parameters

unit : String - unit to get info about

Example

const { Testkit } = require('aa-testkit')

const { Network } = Testkit()
const network = await Network.create().run()

const genesis = await network.getGenesisNode().ready()

const wallet = await network.newHeadlessWallet().ready()
const walletAddress = await wallet.getAddress()

const { unit, error } = await genesis.sendBytes({ toAddress: walletAddress, amount: 1000000 })
await network.witnessUntilStable(unit)

const { unitObj, error } = await wallet.getUnitInfo({ unit: unit })
await network.stop()

UnitObj example

{
  "version": "2.0dev",
  "alt": "3",
  "messages": [
    {
      "app": "payment",
      "payload_location": "inline",
      "payload_hash": "5RTdFnLEHBjY21RltWguOazPNePfnU5LtOR+9VqrFa0=",
      "payload": {
        "outputs": [
          {
            "address": "EGPUJ2WKQMMOD75BMX5YJNYM2BWA22B5",
            "amount": 989401
          },
          {
            "address": "PVMCXUZBEHCFWOLXUDQVNCQZ476LNEW4",
            "amount": 10000
          }
        ],
        "inputs": [
          {
            "unit": "9Iw/Lh1a8ESX/1i+38gzcKeKUwu6TJLefEo7v2oQL6o=",
            "message_index": 0,
            "output_index": 1
          }
        ]
      }
    }
  ],
  "authors": [
    {
      "address": "E5O6LEUDV7QMGFCRF2NGAI65UWSZTXR2",
      "authentifiers": {
        "r": "9c6rYZMJojuiXOErgcxKtj7uoCbQVyX4zfAUJRHGv3Yjlpy30fWThwijedTl6eav7T9f28xfSzPOj9mPW7MzoQ=="
      },
      "definition": [
        "sig",
        {
          "pubkey": "A6V7juMjcMYwf/Cb7agvWYuMbPK79BgX2r0twuIM2JjF"
        }
      ]
    }
  ],
  "timestamp": 1572427125,
  "parent_units": [
    "7Geraevi9Sj3gcdaZH/Rf9AU2V6Caja5TbH4a5+Fwnc="
  ],
  "last_ball": "oXWxUu7e8PyNqOJoHaDFZIwOjtWCSJGV5L4zbhbWn0E=",
  "last_ball_unit": "vHbaBbjajc90AY1/2sDohehFE9Rha0skDnwKnmiWMGc=",
  "witness_list_unit": "RlBMDxYFXnYjlPHyS4GGevPiYZJR5a3xNao0/mHQXRY=",
  "headers_commission": 402,
  "payload_commission": 197,
  "unit": "BKf6iaQFZEd9TzsHrg+IDtN1KHjHMYB2zxn8rZZqNcs=",
  "main_chain_index": 7
}

`node.getUnitProps({ unit })` `: Promise<{ unitProps }>`

Receive unit props.

Promise resolves as { unitProps }

Parameters

unit : String - unit to get info about

Example

const { Testkit } = require('aa-testkit')

const { Network } = Testkit()
const network = await Network.create().run()

const genesis = await network.getGenesisNode().ready()

const wallet = await network.newHeadlessWallet().ready()
const walletAddress = await wallet.getAddress()

const { unit, error } = await genesis.sendBytes({ toAddress: walletAddress, amount: 1000000 })
await network.witnessUntilStable(unit)

const { unitProps } = await wallet.getUnitProps({ unit: unit })
await network.stop()

UnitProps example

{
  unit: 'WhTBfbZK9k1/SxiINGarg455SdpiQNloBdrzbcO29Lo=',
  timestamp: 1574685652,
  level: 1,
  latest_included_mc_index: 0,
  main_chain_index: 1,
  is_on_main_chain: 1,
  is_free: 0,
  is_stable: 1,
  witnessed_level: 0,
  headers_commission: 355,
  payload_commission: 197,
  sequence: 'good',
  author_addresses: ['ZWDAO5YRB3SQZWAOGVNS4NADGIR3RB7Z'],
  witness_list_unit: 'PdiMP8/V2dks18gIP5foxy4WWFYwyURkKyCXQfkZjPU=',
  parent_units: ['PdiMP8/V2dks18gIP5foxy4WWFYwyURkKyCXQfkZjPU='],
}

`node.readAAStateVars(address)` `: Promise<{ vars }>`

Retrieve current network vars state of agent

Returns Promise that resolves to { vars } where vars - state object of agent

Parameters

address : String - address of agent to retrieve state from

Agent Deployment example

See Agent deployment test example

`node.getBalanceOf(address)` `: Promise<balanceObject>`

Get balance of the specified address on the network

Returns Promise that resolves to node balance object

Balance object example

{
   base:{
      stable:0,
      pending:49401,
      is_private:null
   }
}

`node.getOutputsBalanceOf(address)` `: Promise<balanceObject>`

Get outputs balance of the specified address on the network. Do not count comissions earned by this node.

Returns Promise that resolves to node balance object

`node.executeGetter({ aaAddress, getter, args })` `: Promise<{ result, error }>`

Execute getter of given AA.

Returns Promise that resolves to { result, error }, where result a result of getter execution. error will be null on success

Parameters

aaAddress : String - address of the AA

getter : String - getter identifier

args : Array - array of parameters to pass to getter for execution

GenesisNode

Genesis node main function is to start new network and create genesis unit. After this, genesis node serves as witness and source of Bytes. At the moment of network genesis, this node puts on its account 1e15 - 821 Bytes

GenesisNode constructor params

Property	Type	Required	Default	Description
id	String	true		Unique id of this node. Also determines node folder in `testdata` directory
rundir	String	true		Determines where this node will store its data. Absolute path
hub	String	false	`'localhost:6611'`	Address of hub to connect
mnemonic	String	false		Mnemonic to create genesis node from

GenesisNode methods

`genesis.createGenesis()` `: Promise<{ genesisUnit, genesisAddress }>`

Creates network with new genesis unit.

Returns Promise that resolves when genesis complete. Promise resolves to { genesisUnit, genesisAddress }

Example

const { Testkit } = require('aa-testkit')
const path = require('path')

const testdata = path.join(__dirname, '../testdata')
const { Nodes } = Testkit({
  TESTDATA_DIR: testdata,
})
const rundir = path.join(testdata, 'custom')
const genesisNode = new Nodes.GenesisNode({
  rundir,
  id: 'genesis-node',
})
const { genesisUnit, genesisAddress } = await genesisNode.createGenesis()

`genesis.loginToHub()` `: Promise<>`

Send the command to node child to connect to hub. Usefull at network genesis, because hub node starts after genesis node.

Returns Promise that resolves when node connected to hub

`genesis.postWitness()` `: Promise<unit>`

Broadcast new witness to network. Returns Promise that resolves to witness unit hash after broadcasting. Although it does not mean other nodes already received it

Returns Promise that resolves to witness unit hash

Example

const { Testkit } = require('aa-testkit')
const path = require('path')

const testdata = path.join(__dirname, '../testdata')
const { Nodes } = Testkit({
  TESTDATA_DIR: testdata,
})
const rundir = path.join(testdata, 'custom')
const genesisNode = new Nodes.GenesisNode({
  rundir,
  id: 'genesis-node',
})
const { genesisUnit, genesisAddress } = await genesisNode.createGenesis()

const hub = new Nodes.ObyteHub({
  rundir: rundir,
  genesisUnit: genesisUnit,
  initialWitnesses: [genesisAddress],
  id: 'obyte-hub',
})

await genesisNode.ready()
await hub.ready()
await genesisNode.loginToHub()

const wallet = new Nodes.HeadlessWallet({
  rundir: rundir,
  genesisUnit: genesisUnit,
  id: 'headless-wallet-1',
})
await wallet.ready()

const walletAddress = await wallet.getAddress()
// get something to witness
const { unit, error } = await genesisNode.sendBytes({ toAddress: walletAddress, amount: 1000000 })

const witnessUnit = await genesisNode.postWitness()
await Promise.all([genesisNode.waitForUnit(witnessUnit), wallet.waitForUnit(witnessUnit)])

await genesisNode.stop()
await hub.stop()
await wallet.stop()

`genesis.getAddress()` `: Promise<address>`

Request node address from child.

Returns Promise that resolves to node address

`genesis.sendBytes({ toAddress, amount })` `: Promise<{ unit, error }>`

Send Bytes to address

Returns Promise that resolves to { unit, error } after Bytes are sent. error will be null if sending was successfull

Parameters

toAddress : String - address of node that will receive Bytes

amount : Number - amount of Bytes to send

`genesis.sendMulti(opts)` `: Promise<{ unit, error }>`

Send arbitrary data to the network. Same as wallet.sendMulti

ObyteHub

Obyte hub node serves as transport for network. Node receives incomming messages and broadcats them to other nodes

ObyteHub constructor params

Property	Type	Required	Default	Description
id	String	true		Unique id of this node. Also determines node folder in `testdata` directory
rundir	String	true		Determines where this node will store its data. Absolute path
genesisUnit	String	true		The very first unit of the network
port	Number	false	6611	Port the hub will be running on
initialWitnesses	Array[String]	true		Trusted witnesses of this node

ObyteHub methods

`hub.broadcastJoint(joint)`

Broadcasts any joint to the network without validating it.

Parameters

joint : Object - joint object will be passed directly into network.broadcastJoint() of ocore

HeadlessWallet

Headless wallet node provides common network node functionality. It can receive Bytes, send Bytes and broadcast messages

HeadlessWallet constructor params

Property	Type	Required	Default	Description
id	String	true		Unique id of this node. Also determines node folder in `testdata` directory
rundir	String	true		Determines where this node will store its data. Absolute path
mnemonic	String	false		Mnemonic phrase for wallet
genesisUnit	String	true		The very first unit of the network
hub	String	false	`'localhost:6611'`	Address of the hub to connect
isSingleAddress	Boolean	false	true	Defines if node will operate in single address mode

HeadlessWallet methods

`wallet.getAddress()` `: Promise<address>`

Request node address from child.

Returns Promise that resolves to node address

`wallet.getBalance()` `: Promise<balanceObject>`

Retrieve node balance from child.

Returns Promise that resolves to node balance object

Balance object example

{
   base:{
      stable:0,
      pending:49401,
      is_private:null
   }
}

`wallet.sendBytes({ toAddress, amount })` `: Promise<{ unit, error }>`

Send Bytes to address

Returns Promise that resolves to { unit, error } after Bytes are sent. error will be null if sending was successfull

Parameters

toAddress : String - address of node that will receive Bytes

amount : Number - amount of Bytes to send

`wallet.triggerAaWithData({ toAddress, amount, data })` `: Promise<{ unit, error }>`

Trigger AA execution with some data

Returns Promise that resolves to { unit, error } after data is sent. error will be null if sending was successfull

Parameters

toAddress : String - address of AA to trigger

amount : Number - amount of Bytes to send to AA

data : Object - key:value pairs object of data that will be passed to the AA

`wallet.sendMulti(opts)` `: Promise<{ unit, error }>`

Allows to broadcast arbitrary message to network. Opts object is passed directly to issueChangeAddressAndSendMultiPayment method of headless-wallet

Returns Promise that resolves to { unit, error } after message is sent. error will be null if sending was successfull

Parameters

opts : Object - arbitrary message to broadcast

`wallet.issueDivisibleAsset(opts)` `: Promise<{ unit, error }>`

Issue divisible asset

Returns Promise that resolves to { unit, error } after message is sent. error will be null if sending was successfull

Parameters

opts : Object - issue params

Example

const opts = {
  asset: this.assets[name],
  paying_addresses: [myAddress],
  fee_paying_addresses: [myAddress],
  change_address: myAddress,
  to_address: myAddress,
  amount: assetSettings.cap,
}

const { unit, error } = await this.deployer.issueDivisibleAsset(opts)

`wallet.issueInivisibleAsset(opts)` `: Promise<{ unit, error }>`

Issue indivisible asset

Returns Promise that resolves to { unit, error } after message is sent. error will be null if sending was successfull

Parameters

opts : Object - issue params

Example

const opts = {
  asset: this.assets[asset],
  asset_outputs: outputsMap[asset],
  paying_addresses: [myAddress],
  fee_paying_addresses: [myAddress],
  change_address: myAddress,
  tolerance_plus: 0,
  tolerance_minus: 0,
}

const { unit, error } = await this.deployer.issueIndivisibleAsset(opts)

`wallet.deployAgent(source)` `: Promise<{ address, unit, error }>`

Deploy an agent in the network.

Returns Promise that resolves to { address, unit, error }, where address is the address of deployed agent and unit determines unit where agent was deployed. error will be null on success

Parameters

source : Path | String | OJSON - source of AA, can be:

an absolute path to a file containing plaintext agent
an absolute path to a javascript file that exports agent string
an absolute path to a javascript file that exports object in OJSON format
String with valid AA
Javascript object in OJSON format

Example

const { Testkit } = require('aa-testkit')
const { Network } = Testkit()

const network = await Network.create().run()
const genesis = await network.getGenesisNode().ready()

const deployer = await network.newHeadlessWallet().ready()
const deployerAddress = await deployer.getAddress()

// send some bytes to AgentDeployer so it will be able to broadcast message with agent to the network
const { unit, error } = await genesis.sendBytes({ toAddress: deployerAddress, amount: 1000000 })
await network.witnessUntilStable(unit)

// agent in OJSON fromat
const agent = {
  bounce_fees: { base: 10000 },
  messages: [
    {
      app: 'state',
      state: `{
        var['constant_var'] = 'constant_var';
        var['trigger_var'] = trigger.data.var;
        var['sum_var'] = 123 + 456;
      }`
    }
  ]
}

// deploy agent and confirm it on the network
const { address, unit, error } = await deployer.deployAgent(agent)
await network.witnessUntilStable(unit)
await network.stop()

---------------------------------------

`wallet.createAsset(assetDefinition)` `: Promise<{ unit, error }>`

Create an asset in the network.

Returns Promise that resolves to { unit, error }, where unit determines the asset that was created. error will be null on success

Parameters

source : Object - asset definition

Example

const { Testkit } = require('aa-testkit')
const { Network } = Testkit()

const network = await Network.create().run()
const genesis = await network.getGenesisNode().ready()

const creator = await network.newHeadlessWallet().ready()
const creatorAddress = await deployer.getAddress()

// send some bytes to AgentDeployer so it will be able to broadcast message
const { unit, error } = await genesis.sendBytes({ toAddress: creatorAddress, amount: 1000000 })
await network.witnessUntilStable(unit)

const assetDefinition = {
  is_private: false,
  is_transferrable: true,
  auto_destroy: false,
  issued_by_definer_only: true,
  cosigned_by_definer: false,
  spender_attested: false,
  fixed_denominations: false
}

// create asset and confirm it on the network
const { unit, error } = await creator.createAsset(assetDefinition)
await network.witnessUntilStable(unit)
await network.stop()

---------------------------------------

`wallet.getOwnedAddresses()` `: Promise<Array[String]>`

Retreive the array of addresses, owned by this wallet

Returns Promise that resolves to array of string associated with wallet after message is sent.

`wallet.signMessage(message)` `: Promise<{ signedPackage }>`

Sign a message with the wallet address

Returns Promise that resolves to { signedPackage, error }, where signedPackage is an object containing the signed message and its authentifiers. error will be null on success

Parameters

message : String | Object | Array | Number - something that has to be signed

`wallet.composeJoint({ opts, saveJoint = true, broadcastJoint = true })` `: Promise<{ unit, error }>`

Composes new unit and returns it, optionally saving it into wallet storage and broadcasting it.

Returns Promise that resolves to { unit, error }, where unit is the object of unit composed. error will be null on success

Parameters

opts : Object - options directly passed to composer.composeJoint()

saveJoint : Boolean - whether to save joint in own storage or not

broadcastJoint : Boolean - whether to broadcast the joint to the network. You can use .broadcastJoint() method of Hub to later broadcast it.

Example

const { unit: unitObj } = await aliceWallet.composeJoint({
	opts: {
		inputs: [
			{
				message_index: 0,
				output_index: 0,
				unit: aliceInputUnit1,
			},
		],
		input_amount: 100000,
		outputs: [
			{ address: aliceAddress, amount: 0 },
		],
	},
	saveJoint: false,
	broadcastJoint: false,
})

---------------------------------------

`wallet.signUnit(unit)` `: Promise<{ unit, error }>`

Signs the unit using it's authors. Technically, this methods returns the same unit but with authentifiers filled for each author of the unit.

Returns Promise that resolves to { unit, error }, where unit is the object of signed unit. error will be null on success

Parameters

unit : Object - unit object

ObyteExplorer

Obyte explorer node provides DAG explorer of the network for visualization and debugging purposes

ObyteExplorer constructor params

Property	Type	Required	Default	Description
id	String	true		Unique id of this node. Also determines node folder in `testdata` directory
rundir	String	true		Determines where this node will store its data. Absolute path
genesisUnit	String	true		The very first unit of the network
webPort	Number	false	8080	Port theDAG explorer will be started on
initialWitnesses	Array[String]	true		Trusted witnesses of this node
hub	String	false	`'localhost:6611'`	Address of the hub to connect

ObyteExplorer methods

ObyteExplorer node does not have any special methods except common node methods

ObyteExplorer creation example

const { Testkit } = require('aa-testkit')

const { Network } = Testkit()
const network = await Network.create().run()
const genesis = await network.getGenesisNode().ready()

// to have something to display in explorer
const wallet = await network.newHeadlessWallet().ready()
const walletAddress = await wallet.getAddress()

const { unit: unit1 } = await genesis.sendBytes({ toAddress: walletAddress, amount: 1000000 })
await network.witnessUntilStable(unit1)
const { unit: unit2 } = await genesis.sendBytes({ toAddress: walletAddress, amount: 1000000 })
await network.witnessUntilStable(unit2)

// by default DAG explorer will be started on http://localhost:8080
const explorer = await network.newObyteExplorer().ready()

Utils

Utils and helpers from aa-testkit. Can be imported from the package

const { Utils } = require('aa-testkit')
// sleep 5 seconds
await Utils.sleep(5000)

`Utils.sleep(ms)` `: Promise<>`

Pause test execution for ms number of milliseconds. Returns Promise

`Utils.isValidAddress(address)` `: Boolean`

Helper for address validation. Return true if passed argument is valid network address, false otherwise.

`Utils.isValidBase64(b64, len)` `: Boolean`

Helper for base64 strings validation. Return true if passed argument is valid network address, false otherwise.

Parameters

b64 - string to validate

len - optional. Length of the string. Function also validates length if second parameter is present

`Utils.generateMnemonic()` `: String`

Returns randomly generated mnemonic phrase valid for HeadlessWallets

`Utils.getFirstAddress(mnemonic)` `: String`

Returns first wallet address for a given mnemonic pharse.

Parameters

mnemonic - valid mnemonic phrase to derive pubkey from

`Utils.asyncStartHeadlessWallets(network, n)` `: Promise<Array>`

Util that starts n of HeadlessWallet nodes asynchronously. Helps to speed up test execution when starting a lot of HeadlessWallet nodes.

Returns Returns Promise that resolves to Array of HeadlessWallets:

Parameters

network - network to start nodes on

n - number of nodes to start

Example

const { Testkit, Utils } = require('aa-testkit')
const { Network } = Testkit()

const network = await Network.create().run()
const genesis = await network.getGenesisNode().ready()

const [wallet1, wallet2, wallet3] = await Utils.asyncStartHeadlessWallets(network, 3)
await network.stop()

Mocha Example

This could be helpfull if you want to assign created wallets to this in mocha tests

this.network = await Network.create().run()
this.genesis = await this.network.getGenesisNode().ready()

this.teamRed = {}
this.teamBlue = {}; // mind the semicolon. Otherwise use of destructuring assignment on the next line will lead to incorrect syntax.
[
  this.deployer,
  this.teamRed.founder,
  this.teamRed.alice,
  this.teamRed.bob,
  this.teamBlue.founder,
  this.teamBlue.mark,
  this.teamBlue.eva,
] = await Utils.asyncStartHeadlessWallets(this.network, 7)

`Utils.asyncStartHeadlessWalletsWithMnemonics(network, mnemonics)` `: Promise<Array>`

Same as asyncStartHeadlessWallets, but this function starts wallets for known array of mnemonics. Order of wallet nodes in returning array is preserved

Returns Returns Promise that resolves to Array of HeadlessWallets:

Parameters

network - network to start nodes on

mnemonics - an array of mnemonic phrases

`Utils.countCommissionInUnits(node, units)` `: Promise(commissions)`

Helper to count headers and payload commissions in units.

Returns Returns Promise that resolves to object:

{
  error,
  total_headers_commission,
  total_payload_commission
}

total_headers_commission is the sum of headers commissions from passed units.

total_payload_commission is the sum of payload commissions from passed units.

error will be null if no errors present.

error will be the first faced error otherwise.

total_payload_commission and total_headers_commission will be null if error is present

Parameters

node - any running node that supports node.getUnitInfo

units - array of unit hashes to count the commissions on

Example

const { Testkit, Utils } = require('aa-testkit')
const { Network } = Testkit()

const network = await Network.create().run()
const genesis = await network.getGenesisNode().ready()

const wallet = await network.newHeadlessWallet().ready()
const { unit, error } = await genesis.sendBytes({
  toAddress: await wallet.getAddress(),
  amount: 1e9,
})

const commissions = await Utils.countCommissionInUnits(wallet, [unit])
await network.stop()

`Utils.hasOnlyTheseExternalPayments(unit, arrExpectedPayments)` `: Boolean`

Helper to check the outputs of a response unit. Returns true if the unit contains exclusively the payment described in arrExpectedPayments.

Parameters

unit - unit object

arrExpectedPayments - array of payment objects having each this structure

{
  address,
  amount,
  asset
}

where address is the recipient address, amount the amount sent, asset is the asset hash (null for payment in bytes)

Example

const { Testkit, Utils } = require('aa-testkit')
const { Network, Utils } = Testkit()

const network = await Network.create().run()
const genesis = await network.getGenesisNode().ready()
const sender = await network.newHeadlessWallet().ready()

const { unit } = await genesis.sendBytes({ toAddress: await sender.getAddress(), amount: 1e9 })
await network.witnessUntilStable(unit)

const asset_1 = (await sender.createAsset({
	is_private: false,
	is_transferrable: true,
	auto_destroy: false,
	issued_by_definer_only: true,
	cosigned_by_definer: false,
	spender_attested: false,
	fixed_denominations: false,
})).unit

await network.witnessUntilStable(asset_1)

const { unit } = await sender.sendMulti({
	asset_outputs: [{
		address: 'WDZZ6AGCHI5HTS6LJD3LYLPNBWZ72DZI',
		amount: 80006,
	}, {
		address: '3W43U3SHKBVDUP7T7YOJOY5NM353HA5C',
		amount: 3806,
	}],
	base_outputs: [{
		address: '3W43U3SHKBVDUP7T7YOJOY5NM353HA5C',
		amount: 1875513,
	}],
	change_address: await sender.getAddress(),
	asset: asset_1,
})

const { unitObj } = await sender.getUnitInfo({ unit })

const isValid = Utils.hasOnlyTheseExternalPayments(unitObj, [{
	address: 'WDZZ6AGCHI5HTS6LJD3LYLPNBWZ72DZI',
	amount: 80006,
	asset: asset_1,
}, {
	address: '3W43U3SHKBVDUP7T7YOJOY5NM353HA5C',
	amount: 3806,
	asset: asset_1,
}, {
	address: '3W43U3SHKBVDUP7T7YOJOY5NM353HA5C',
	amount: 1875513,
}])

`Utils.getExternalPayments(unit)` `: Array`

Returns an array of external payments for a given unit object

Parameters

unit - unit object

Custom Nodes

Custom Node API allows to extend existing app based on headless-obyte and integrate it with aa-testkit. This allows to automate testing of an app and run it on devnet with tools provided by aa-testkit.

This API consits of two parts which communicate with each other via IPC: Custom.Node and Custom.Child. They are two classes that can be imported from testkit and should be extended by user

To obtain the working template with example run the following command:

# requires npm 5.2+ installed
npx create-aa my-agent -t custom-node

Custom Node

Custom.Node is responsilbe for:

providing an user defined api for aa-testkit
sending and receiving messages from Custom.Child

Custom.Node already provides any method available in HeadlessWallet node like getBalance, sendBytes, getAddress etc

const path = require('path')
const { Testkit } = require('aa-testkit')

const { Custom } = Testkit({
	TESTDATA_DIR: path.join(process.cwd(), 'testdata'),
})

// implementation should be inherited from Custom.Node
class MyNode extends Custom.Node {

  // `childPath` should be overloaded and return absolute path to file with Custom.Child implementation
	childPath () {
		return path.join(__dirname, './MyChild')
	}

  // messages that are sent from Custom.Child via `this.sendCustomMessage` can be handled in `handleCustomMessage`
	handleCustomMessage (payload) {
    switch (payload.type) {
		case 'pong':
      // use `this.sendCustomMessage` to send arbitrary JSON data to `Custom.Node`
			this.emit('pong', payload.data)
      break
    }
  }

  // any custom method declared in this class will be available in testkit
  myFunction () {
    // use Promise based syntax to wait and receive data from child
    return new Promise(resolve => {
      this.once('pong', (data) => resolve(data))
      // to send an arbitrary JSON data to Custom.Child use `this.sendCustomCommand` method
      this.sendCustomCommand({ type: 'ping', data: 'hello' })
    })
  }

}

module.exports = MyNode

Custom Child

Custom.Child is responsilbe for:

controlling user app and exposing its functions to testkit indirectly via Custom.Node
sending and receiving messages from Custom.Node

Custom.Child is being run in separate process which also runs user app and exposes its functions to Custom.Node

const path = require('path')
const { Testkit } = require('aa-testkit')

const { Custom } = Testkit({
	TESTDATA_DIR: path.join(process.cwd(), 'testdata'),
})

// implementation should be inherited from Custom.Child
class MyNodeChild extends Custom.Child {
  run () {
	  // any initialization code goes here
		// this method should require and run user app
	}

  // `sendCustomCommand` from MyNode interface can be handled here

  // messages that are sent from Custom.Node via `this.sendCustomCommand` can be handled in `handleCustomCommand`
	async handleCustomCommand (payload) {
		switch (payload.type) {
		case 'ping':
			// use `this.sendCustomMessage` to send arbitrary JSON data to `Custom.Node`
			this.sendCustomMessage({ type: 'pong', data: payload.data })
      break
    }
	}
}

// this is mandatory to start child correctly on devnet
const child = new MyNodeChild(process.argv)
// start Custom.Child process and user app
child.start()

Testkit Integration

After implementing node and child API, this node can be run inside testkit

const MyNode = require('./MyNode')

// running custom node using `.with` syntax
this.network = await Network.create()
  // first param is the implementation of Custom.Node, second is balances object like in `.with.wallet` syntax
  .with.custom(MyNode, { alice: 100e9 })
  .run()

// node is ready to execute methods from Custom.Node
const data = await this.network.custom.alice.myFunction()

// or create custom node directly
const custom = await this.network.newCustomNode(MyNode).ready()
const data = await custom.myFunction()

Test Examples

Setup network and send some payments over the network

const assert = require('assert')
const { Testkit } = require('aa-testkit')
const path = require('path')

const testdata = path.join(__dirname, '../testdata')
const { Network } = Testkit({
  TESTDATA_DIR: testdata,
})

const network = await Network.create().run()
const genesis = await network.getGenesisNode().ready()

const alice = await network.newHeadlessWallet().ready()
const bob = await network.newHeadlessWallet().ready()

const aliceAddress = await alice.getAddress()
const bobAddress = await bob.getAddress()

const { unit: unit1 } = await genesis.sendBytes({ toAddress: aliceAddress, amount: 100000 })
await network.sync()

let aliceBalance = await alice.getBalance()
assert(aliceBalance.base.pending === 100000)
await network.witnessUntilStable(unit1)

aliceBalance = await alice.getBalance()
assert(aliceBalance.base.stable === 100000)

const { unit: unit2 } = await alice.sendBytes({ toAddress: bobAddress, amount: 50000 })
await network.sync()

aliceBalance = await alice.getBalance()
assert(aliceBalance.base.pending === 49401)

let bobBalance = await bob.getBalance()
assert(bobBalance.base.pending === 50000)

await network.witnessUntilStable(unit2)

aliceBalance = await alice.getBalance()
assert(aliceBalance.base.stable === 49756)

bobBalance = await bob.getBalance()
assert(bobBalance.base.stable === 50000)

await network.stop()

Agent deployment and reading state vars

const assert = require('assert')
const { Testkit } = require('aa-testkit')
const isValidAddress = require('ocore/validation_utils').isValidAddress
const path = require('path')

const agentString = `{
  bounce_fees: { base: 10000 },
  messages: [
    {
      app: 'state',
      state: "{
        var['constant_var'] = 'constant_var';
        var['trigger_var'] = trigger.data.var;
        var['sum_var'] = 123 + 456;
      }"
    }
  ]
}`

const testdata = path.join(__dirname, '../testdata')
const { Network } = Testkit({
  TESTDATA_DIR: testdata,
})

const network = await Network.create().run()
const genesis = await network.getGenesisNode().ready()

// agent deployment
const deployer = await network.newHeadlessWallet().ready()
const deployerAddress = await deployer.getAddress()

const wallet = await network.newHeadlessWallet().ready()
const walletAddress = await wallet.getAddress()

await genesis.sendBytes({ toAddress: deployerAddress, amount: 1000000 })
const { unit } = await genesis.sendBytes({ toAddress: walletAddress, amount: 1000000 })
await network.witnessUntilStable(unit)

const { address: agentAddress, unit: agentUnit } = await deployer.deployAgent(agentString)

assert(isValidAddress(agentAddress))
await network.witnessUntilStable(agentUnit)

// reading state vars
const { unit } = await wallet.triggerAaWithData({
  toAddress: agentAddress,
  amount: 10000,
  data: {
    var: 'trigger_var',
  },
})

await network.witnessUntilStable(unit)

const { vars } = await deployer.readAAStateVars(agentAddress)

assert(vars.constant_var === 'constant_var')
assert(vars.trigger_var === 'trigger_var')
assert(vars.sum_var === '579')

await network.stop()

Time-dependent AA and network timetravel feature

const assert = require('assert')
const { Testkit } = require('aa-testkit')
const isValidAddress = require('ocore/validation_utils').isValidAddress
const path = require('path')

const agentString = `{
  bounce_fees: { base: 10000 },
  init: '{
    $future_ts = 1893456000; // Jan 1, 2030
  }',
  messages: {
    cases: [
      {
        if: '{timestamp > $future_ts}',
        messages: [
          {
            app: 'state',
            state: '{
              var['time'] = 'future';
            }'
          },
        ]
      },
      {
        if: '{timestamp <= $future_ts}',
        messages: [
          {
            app: 'state',
            state: '{
              var['time'] = 'past';
            }'
          },
        ]
      }
    ]
  }
}`

const testdata = path.join(__dirname, '../testdata')
const { Network } = Testkit({
  TESTDATA_DIR: testdata,
})

const network = await Network.create().run()
const genesis = await network.getGenesisNode().ready()

// agent deployment
const deployer = await network.newHeadlessWallet().ready()
const deployerAddress = await deployer.getAddress()

const wallet = await network.newHeadlessWallet().ready()
const walletAddress = await wallet.getAddress()

await genesis.sendBytes({ toAddress: deployerAddress, amount: 1000000 })
const { unit } = await genesis.sendBytes({ toAddress: walletAddress, amount: 1000000 })
await network.witnessUntilStable(unit)

const { address: agentAddress, unit: agentUnit } = await deployer.deployAgent(agentString)

assert(isValidAddress(agentAddress))
await network.witnessUntilStable(agentUnit)

const { unit: unitBeforeTravel } = await wallet.sendBytes({
  toAddress: agentAddress,
  amount: 10000,
})
await network.witnessUntilStable(unitBeforeTravel)

// check state vars before timetravel
let state = await deployer.readAAStateVars(agentAddress)
assert(state.vars.time === 'past')

// Timetravel network
const { error } = await network.timetravel({ to: '2050-01-01' })

const { unit: unitAfterTravel } = await wallet.sendBytes({
  toAddress: agentAddress,
  amount: 10000,
})
await network.witnessUntilStable(unitAfterTravel)

state = await deployer.readAAStateVars(agentAddress)

assert(state.vars.time === 'future')

await network.stop()

Get unit info

const assert = require('assert')
const { Testkit } = require('aa-testkit')
const path = require('path')

const testdata = path.join(__dirname, '../testdata')
const { Network } = Testkit({
  TESTDATA_DIR: testdata,
})

const network = await Network.create().run()
const genesis = await network.getGenesisNode().ready()

const wallet = await network.newHeadlessWallet().ready()

const walletAddress = await wallet.getAddress()

const { unit } = await genesis.sendBytes({ toAddress: walletAddress, amount: 100000 })
await network.witnessUntilStable(unit)

const { unitObj, error } = await wallet.getUnitInfo({ unit })
assert(error === null)

assert(unitObj.hasOwnProperty('unit'))
assert(unitObj.hasOwnProperty('ball'))

assert(unitObj.hasOwnProperty('version'))
assert(unitObj.hasOwnProperty('alt'))
assert(unitObj.hasOwnProperty('messages'))
assert(unitObj.hasOwnProperty('authors'))
assert(unitObj.hasOwnProperty('timestamp'))
assert(unitObj.hasOwnProperty('parent_units'))
assert(unitObj.hasOwnProperty('last_ball'))
assert(unitObj.hasOwnProperty('last_ball_unit'))
assert(unitObj.hasOwnProperty('witness_list_unit'))
assert(unitObj.hasOwnProperty('headers_commission'))
assert(unitObj.hasOwnProperty('payload_commission'))

assert(unitObj.hasOwnProperty('unit'))
assert(unitObj.unit === unit)

assert(unitObj.hasOwnProperty('main_chain_index'))
assert(unitObj.main_chain_index === 1)

await network.stop()

unitObj content

{
  "unit": {
    "version": "2.0dev",
    "alt": "3",
    "messages": [
      {
        "app": "payment",
        "payload_location": "inline",
        "payload_hash": "rIqo7sri7Vt9yR/P22zd2UNAM6lNx9eJtTsO8Dp2WUI=",
        "payload": {
          "outputs": [
            {
              "address": "KMGCRWPAWBR4G66J5ZPYV2YLYCZ7MS7T",
              "amount": 100000
            },
            {
              "address": "MF3BUCZD4ACJWEJH7R6FA5XP23WPYK2M",
              "amount": 899448
            }
          ],
          "inputs": [
            {
              "unit": "dnAsJUmfXLEoQEBk2bZ0zKLBChSqfCWUalUOhokQ/x8=",
              "message_index": 0,
              "output_index": 0
            }
          ]
        }
      }
    ],
    "authors": [
      {
        "address": "2VEZBTGBZAQBRUPLMN4QTCN5YHJ5ZIS7",
        "authentifiers": {
          "r": "Z8Ucy7+yVio6jlvzi2C/ig6IF0fHVYW6idV674rHT2Bn3FV+/XkIrHQ0ClHNKT1iMQwilMLycWnNKmN8adqSSw=="
        }
      }
    ],
    "timestamp": 1572446684,
    "parent_units": [
      "dnAsJUmfXLEoQEBk2bZ0zKLBChSqfCWUalUOhokQ/x8="
    ],
    "last_ball": "THj5ba6gkebexKppJVp4TyJ3Qhq9CKSOmSQST7Zifz4=",
    "last_ball_unit": "dnAsJUmfXLEoQEBk2bZ0zKLBChSqfCWUalUOhokQ/x8=",
    "witness_list_unit": "dnAsJUmfXLEoQEBk2bZ0zKLBChSqfCWUalUOhokQ/x8=",
    "headers_commission": 355,
    "payload_commission": 197,
    "unit": "oGv2HJtcC/SILJfHXo44x43PCHds+HAhnouaqyVD/yE=",
    "main_chain_index": 1
  },
  "ball": "mj9Cze6RocUcuQlLT6G5XOG1UWv28tUSQoYU3YNgUhQ="
}

Get AA execution response

const agentString = `{
  bounce_fees: { base: 10000 },
  messages: [
    {
      init: '{
        $datafeed = trigger.data.dataFeedPayload;
        response['dataFeedAaResponse'] = 'aa response!';
      }',
      app: 'data_feed',
      payload: {
        dataFeedPayload: '{
          if ($datafeed)
            return $datafeed;
          'no datafeed provided'
        }'
      }
    }
  ]
}`

const assert = require('assert')
const { Testkit } = require('aa-testkit')
const { Network } = Testkit()

const network = await Network.create().run()
const genesis = await network.getGenesisNode().ready()
const explorer = await network.newObyteExplorer().ready()

const deployer = await network.newHeadlessWallet().ready()
const deployerAddress = await deployer.getAddress()

const wallet = await network.newHeadlessWallet().ready()
const walletAddress = await wallet.getAddress()

const { unit: unit1 } = await genesis.sendBytes({ toAddress: walletAddress, amount: 1e9 })
await network.witnessUntilStable(unit1)

const { unit: unit2 } = await genesis.sendBytes({ toAddress: deployerAddress, amount: 1e9 })
await network.witnessUntilStable(unit2)

const { address: agentAddress, unit: agentDeploymentUnit, error: agentDeploymentError } = await deployer.deployAgent(agentString)

await network.witnessUntilStable(agentDeploymentUnit)

const { unit, error } = await wallet.triggerAaWithData({
  toAddress: agentAddress,
  amount: 10000,
  data: {
    dataFeedPayload: 'this will be a datafeed',
  },
})

await network.witnessUntilStable(unit)
const { response } = await network.getAaResponseToUnit(unit)

assert(response.response.responseVars.dataFeedAaResponse === 'aa response!')

const aaResponseUnit = response.response_unit
const { unitObj, error: aaResponseUnitError } = await wallet.getUnitInfo({ unit: aaResponseUnit })

const dataFeedMessage = unitObj.messages.find(e => e.app === 'data_feed')
assert(dataFeedMessage.payload.dataFeedPayload === 'this will be a datafeed')

await network.stop()

Writing Tests With Mocha

Although aa-testkit can be used with any test runner or even without one, we recommend using mocha for writing tests.

Some examples of mocha tests set up can be found inside test data of aa-testkit module

Sending Payments

AA deployment

AA state vars checking

Timetravel feature

Retrieving AA response

Name		Name	Last commit message	Last commit date
Latest commit History 102 Commits
config		config
src		src
test		test
.editorconfig		.editorconfig
.eslintrc.js		.eslintrc.js
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
README.md		README.md
main.js		main.js
package.json		package.json

tonyofbyteball/aa-testkit

Folders and files

Latest commit

History

Repository files navigation

aa-testkit

Table of contents

Quick Start

Usage

Testkit API

Testkit(config) : { Network, Nodes }

Parameters

Network API

Network.create(genesisParams, hubParams) : <network>

Parameters

Network.create.with

.with.wallet({ walletName: balances }[, mnemonic: String])

.with.agent({ agentName: source })

.with.asset({ assetName: assetDefinition })

.with.numberOfWitnesses(number)

.with.custom(MyNode, { nodeName: balances })

.network.deployer

.with.explorer({ port })

network.getGenesisNode() : <GenesisNode>

network.getHub() : <ObyteHub>

network.newHeadlessWallet(params) : <HeadlessWallet>

Parameters

network.newObyteExplorer(params) : <ObyteExplorer>

Parameters

network.newCustomNode(MyNode) : <Custom.Node>

Parameters

network.sync() : Promise<>

network.witnessUntilStable(unit) : Promise<>

Parameters

network.witnessUntilStableOnNode(node, unit) : Promise<>

Parameters

network.getAaResponseToUnit(unit) : Promise<{ response }>

Parameters

getAaResponseToUnitOnNode(node, unit) : Promise<{ response }>

Parameters

getAaResponseToUnitByAA(unit, aa) : Promise<{ response }>

Parameters

getAaResponseToUnitByAAOnNode(node, unit, aa) : Promise<{ response }>

Parameters

network.timetravel({ to, shift }) : Promise<{ error: String, timestamp: Number }>

Parameters

network.timefreeze() : Promise<{ error: string }>

network.timerun() : Promise<{ error: string }>

network.stop() : Promise<>

Nodes API

Common node methods

node.ready() : Promise<>

node.stop() : Promise<>

node.waitForNewJoint() : Promise<joint>

node.waitForUnit(unit) : Promise<>

node.waitForUnits(units) : Promise<>

node.timetravel({ to, shift }) : Promise<{ error: String, timestamp: Number }>

Parameters

node.getTime() : Promise<{ time: number }>

node.getLastMCI() : Promise<mci: number>

node.getUnitInfo({ unit }) : Promise<{ unitObj, error }>

Parameters

node.getUnitProps({ unit }) : Promise<{ unitProps }>

Parameters

node.readAAStateVars(address) : Promise<{ vars }>

Parameters

node.getBalanceOf(address) : Promise<balanceObject>

node.getOutputsBalanceOf(address) : Promise<balanceObject>

node.executeGetter({ aaAddress, getter, args }) : Promise<{ result, error }>

Parameters

GenesisNode

GenesisNode constructor params

GenesisNode methods

genesis.createGenesis() : Promise<{ genesisUnit, genesisAddress }>

genesis.loginToHub() : Promise<>

genesis.postWitness() : Promise<unit>

genesis.getAddress() : Promise<address>

genesis.sendBytes({ toAddress, amount }) : Promise<{ unit, error }>

Parameters

genesis.sendMulti(opts) : Promise<{ unit, error }>

`Testkit(config)` `: { Network, Nodes }`

`Network.create(genesisParams, hubParams)` `: <network>`

`Network.create.with`

`.with.wallet({ walletName: balances }[, mnemonic: String])`

`.with.agent({ agentName: source })`

`.with.asset({ assetName: assetDefinition })`

`.with.numberOfWitnesses(number)`

`.with.custom(MyNode, { nodeName: balances })`

`.network.deployer`

`.with.explorer({ port })`

`network.getGenesisNode()` `: <GenesisNode>`

`network.getHub()` `: <ObyteHub>`

`network.newHeadlessWallet(params)` `: <HeadlessWallet>`

`network.newObyteExplorer(params)` `: <ObyteExplorer>`

`network.newCustomNode(MyNode)` `: <Custom.Node>`

`network.sync()` `: Promise<>`

`network.witnessUntilStable(unit)` `: Promise<>`

`network.witnessUntilStableOnNode(node, unit)` `: Promise<>`

`network.getAaResponseToUnit(unit)` `: Promise<{ response }>`

`getAaResponseToUnitOnNode(node, unit)` `: Promise<{ response }>`

`getAaResponseToUnitByAA(unit, aa)` `: Promise<{ response }>`

`getAaResponseToUnitByAAOnNode(node, unit, aa)` `: Promise<{ response }>`

`network.timetravel({ to, shift })` `: Promise<{ error: String, timestamp: Number }>`

`network.timefreeze()` `: Promise<{ error: string }>`

`network.timerun()` `: Promise<{ error: string }>`

`network.stop()` `: Promise<>`

`node.ready()` `: Promise<>`

`node.stop()` `: Promise<>`

`node.waitForNewJoint()` `: Promise<joint>`

`node.waitForUnit(unit)` `: Promise<>`

`node.waitForUnits(units)` `: Promise<>`

`node.timetravel({ to, shift })` `: Promise<{ error: String, timestamp: Number }>`

`node.getTime()` `: Promise<{ time: number }>`

`node.getLastMCI()` `: Promise<mci: number>`

`node.getUnitInfo({ unit })` `: Promise<{ unitObj, error }>`

`node.getUnitProps({ unit })` `: Promise<{ unitProps }>`

`node.readAAStateVars(address)` `: Promise<{ vars }>`

`node.getBalanceOf(address)` `: Promise<balanceObject>`

`node.getOutputsBalanceOf(address)` `: Promise<balanceObject>`

`node.executeGetter({ aaAddress, getter, args })` `: Promise<{ result, error }>`

`genesis.createGenesis()` `: Promise<{ genesisUnit, genesisAddress }>`

`genesis.loginToHub()` `: Promise<>`

`genesis.postWitness()` `: Promise<unit>`

`genesis.getAddress()` `: Promise<address>`

`genesis.sendBytes({ toAddress, amount })` `: Promise<{ unit, error }>`

`genesis.sendMulti(opts)` `: Promise<{ unit, error }>`

`hub.broadcastJoint(joint)`

`wallet.getAddress()` `: Promise<address>`

`wallet.getBalance()` `: Promise<balanceObject>`

`wallet.sendBytes({ toAddress, amount })` `: Promise<{ unit, error }>`

`wallet.triggerAaWithData({ toAddress, amount, data })` `: Promise<{ unit, error }>`

`wallet.sendMulti(opts)` `: Promise<{ unit, error }>`

`wallet.issueDivisibleAsset(opts)` `: Promise<{ unit, error }>`

`wallet.issueInivisibleAsset(opts)` `: Promise<{ unit, error }>`

`wallet.deployAgent(source)` `: Promise<{ address, unit, error }>`

`wallet.createAsset(assetDefinition)` `: Promise<{ unit, error }>`

`wallet.getOwnedAddresses()` `: Promise<Array[String]>`

`wallet.signMessage(message)` `: Promise<{ signedPackage }>`

`wallet.composeJoint({ opts, saveJoint = true, broadcastJoint = true })` `: Promise<{ unit, error }>`

`wallet.signUnit(unit)` `: Promise<{ unit, error }>`

`Utils.sleep(ms)` `: Promise<>`

`Utils.isValidAddress(address)` `: Boolean`

`Utils.isValidBase64(b64, len)` `: Boolean`

`Utils.generateMnemonic()` `: String`

`Utils.getFirstAddress(mnemonic)` `: String`

`Utils.asyncStartHeadlessWallets(network, n)` `: Promise<Array>`

`Utils.asyncStartHeadlessWalletsWithMnemonics(network, mnemonics)` `: Promise<Array>`

`Utils.countCommissionInUnits(node, units)` `: Promise(commissions)`

`Utils.hasOnlyTheseExternalPayments(unit, arrExpectedPayments)` `: Boolean`

`Utils.getExternalPayments(unit)` `: Array`

Packages