State Management

algorand-typescript-testing provides tools to test state-related abstractions in Algorand smart contracts. This guide covers global state, local state, boxes, and scratch space management.

import * as algots from '@algorandfoundation/algorand-typescript';

import { TestExecutionContext } from '@algorandfoundation/algorand-typescript-testing';

// Create the context manager for snippets below

const ctx = new TestExecutionContext();

Global State

Global state is represented as instance attributes on algots.Contract and algots.arc4.Contract classes.

class MyContract extends algots.arc4.Contract {

stateA = algots.GlobalState<algots.uint64>({ key: 'globalStateA' });

stateB = algots.GlobalState({ initialValue: algots.Uint64(1), key: 'globalStateB' });

}

// In your test

const contract = ctx.contract.create(MyContract);

contract.stateA.value = algots.Uint64(10);

contract.stateB.value = algots.Uint64(20);

Local State

Local state is defined similarly to global state, but accessed using account addresses as keys.

class MyContract extends algots.arc4.Contract {

localStateA = algots.LocalState<algots.uint64>({ key: 'localStateA' });

}

// In your test

const contract = ctx.contract.create(MyContract);

const account = ctx.any.account();

contract.localStateA(account).value = algots.Uint64(10);

Boxes

The framework supports various Box abstractions available in algorand-typescript.

class MyContract extends algots.arc4.Contract {

box: algots.Box<algots.uint64> | undefined;

boxMap = algots.BoxMap<algots.bytes, algots.uint64>({ keyPrefix: 'boxMap' });

@algots.arc4.abimethod()

someMethod(keyA: algots.bytes, keyB: algots.bytes, keyC: algots.bytes) {

this.box = algots.Box<algots.uint64>({ key: keyA });

this.box.value = algots.Uint64(1);

this.boxMap.set(keyB, algots.Uint64(1));

this.boxMap.set(keyC, algots.Uint64(2));

}

}

// In your test

const contract = ctx.contract.create(MyContract);

const keyA = algots.Bytes('keyA');

const keyB = algots.Bytes('keyB');

const keyC = algots.Bytes('keyC');

contract.someMethod(keyA, keyB, keyC);

// Access boxes

const boxContent = ctx.ledger.getBox(contract, keyA);

expect(ctx.ledger.boxExists(contract, keyA)).toBe(true);

// Set box content manually

ctx.ledger.setBox(contract, keyA, algots.op.itob(algots.Uint64(1)));

Scratch Space

Scratch space is represented as a list of 256 slots for each transaction.

@algots.contract({ scratchSlots: [1, 2, { from: 3, to: 20 }] })

class MyContract extends algots.Contract {

approvalProgram(): boolean {

algots.op.Scratch.store(1, algots.Uint64(5));

algots.assert(algots.op.Scratch.loadUint64(1) === algots.Uint64(5));

return true;

}

}

// In your test

const contract = ctx.contract.create(MyContract);

const result = contract.approvalProgram();

expect(result).toBe(true);

const scratchSpace = ctx.txn.lastGroup.getScratchSpace();

expect(scratchSpace[1]).toEqual(5);

For more detailed information, explore the example contracts in the examples/ directory, the coverage page, and the API documentation.

// test cleanup

ctx.reset();