Store

Defined in: packages/store-kit/src/Store.ts:69

A specialized Store class extending from @tanstack/store, designed for managing and interacting with application-level state on the Algorand blockchain.

The class provides methods to deploy, initialize, save, and retrieve application state stored in Algorand application storage boxes. It leverages the AlgorandClient for blockchain interactions and a Deployer for deploying and signing transactions.

Get Started

import {Store} from '@awesome-algorand/store-kit'
const store = new Store({
  foo: "bar",
  baz: 123,
})

await store.setAlgorand(algorand).init("contract-name")

See the Store.constructor method for more information on how to instantiate the class.

Template

The type of the state managed by the store. This may be omitted in favor of type inference.

Extends

• Store<TState>

Type Parameters

• TState

Implements

• StoreInterface<TState>

Constructors

new Store()

new Store<TState>(initialState): Store<TState>

Defined in: packages/store-kit/src/Store.ts:172

A specialized Store class extending from @tanstack/store, designed for managing and interacting with application-level state on the Algorand blockchain.

Stores need both a valid Deployer and AlgorandClient to interact with the blockchain. This is done via the Store.setAccount and Store.setAlgorand methods respectively

Parameters

initialState

TState

initial data to populate the store with

Returns

Store<TState>

Examples

Create

import {Store} from '@awesome-algorand/store-kit'

const bearStore = new Store({
  count: 5,
  species: "Grizzly"
})

Configure

import {AlgorandClient} from '@algorandfoundation/algokit-utils'
bearStore
  .setAlgorand(AlgorandClient.fromEnvironment())

Add Account

await bearStore
  // Add a Deployer account to the store
  .setAccount(await algorand.account.fromEnvironment('DEPLOYER'))

Deploy

await bearStore
  // initialize the typed clients and deploy the contract by default
  .init('grizzly-bears')

 console.log(bearStore.appId)

Hydrate

[!WARNING] Only hydrate the store when it has been initialized

await bearStore
  // Set the application id and rehydrate the store
  .setAppId(1337n)

Overrides

BaseStore<TState>.constructor

Properties

appId

appId: null | bigint = null

Defined in: packages/store-kit/src/Store.ts:112

---

deltas

deltas: Map<string, string>

Defined in: packages/store-kit/src/Store.ts:74

---

listeners

listeners: Set<Listener<TState>>

Defined in: node_modules/@tanstack/store/dist/esm/store.d.ts:19

Inherited from

BaseStore.listeners

---

network

network: NetworkId = NetworkId.LOCALNET

Defined in: packages/store-kit/src/Store.ts:75

---

options?

optional options: StoreOptions<TState, (cb) => TState>

Defined in: node_modules/@tanstack/store/dist/esm/store.d.ts:22

Inherited from

BaseStore.options

---

prevState

prevState: TState

Defined in: node_modules/@tanstack/store/dist/esm/store.d.ts:21

Inherited from

BaseStore.prevState

---

setState()

setState: (updater) => void

Defined in: node_modules/@tanstack/store/dist/esm/store.d.ts:25

Parameters

updater

(cb) => TState

Returns

void

Inherited from

BaseStore.setState

---

state

state: TState

Defined in: node_modules/@tanstack/store/dist/esm/store.d.ts:20

Inherited from

BaseStore.state

---

status

status: StoreStatus = "unknown"

Defined in: packages/store-kit/src/Store.ts:73

---

subscribe()

subscribe: (listener) => () => void

Defined in: node_modules/@tanstack/store/dist/esm/store.d.ts:24

Parameters

listener

Listener<TState>

Returns

Function

Returns

void

Inherited from

BaseStore.subscribe

Accessors

dirty

Get Signature

get dirty(): boolean

Defined in: packages/store-kit/src/Store.ts:77

Returns

boolean

Methods

assemble()

assemble(): Promise<TState>

Defined in: packages/store-kit/src/Store.ts:561

Assembles and retrieves data stored in the storage boxes of an application, decodes the content, and formats it into a structured object.

Returns

Promise<TState>

Returns a Promise that resolves to an object of type T, containing the decoded and processed data from the application storage boxes.

Throws

Throws an error if the client is undefined, indicating that initialization has not been completed.

Implementation of

StoreInterface.assemble

---

balance()

balance(): Promise<bigint>

Defined in: packages/store-kit/src/Store.ts:200

Returns

Promise<bigint>

---

converge()

converge(state): Promise<LodashComposer<[]>>

Defined in: packages/store-kit/src/Store.ts:533

Parameters

state

any

Returns

Promise<LodashComposer<[]>>

---

destroy()

destroy(): Promise<void>

Defined in: packages/store-kit/src/Store.ts:571

Returns

Promise<void>

---

init()

init(name?, sync?): Promise<Store<TState>>

Defined in: packages/store-kit/src/Store.ts:353

Initializes the store with the provided configurations. This method sets up a client instance, handles deployment if necessary, and syncs the state as required.

Parameters

name?

string = "Lodash"

The identifier or name of the app/client to be initialized.

sync?

boolean = true

Indicates whether to synchronize the state after initialization.

Returns

Promise<Store<TState>>

Throws

Error Will throw an error if a client already exists, if the Algorand client is missing, or if required prerequisites for initialization or deployment are not met.

---

save()

save(): Promise<void>

Defined in: packages/store-kit/src/Store.ts:461

Saves the current state to the network. This method ensures that the app is initialized and a deployer is provided before attempting to save. It synchronizes the state by mapping paths to their respective values and storing them on-chain.

Returns

Promise<void>

Resolves when the state has been successfully saved to the network.

Throws

Throws an error if the app has not been initialized with a client or if a deployer is not provided.

Example

Basic Usage

// Import a custom Store instance
import {exampleStore} from "./exampleStore"
// Save the state to the network
await exampleStore.save()

Custom Deployer

Deployer can be passed as an argument to the save method

// Import a custom Store instance
import {exampleStore} from "./exampleStore"
// Define a deployer
const deployer = await algorand.account.fromMnemonic("example deployer mnemonic")
// Save the state to the network
await exampleStore.save(deployer)

---

setAccount()

setAccount(deployer, sync): Store<TState>

Defined in: packages/store-kit/src/Store.ts:210

Sets the account for the given deployer and determines synchronization behavior.

This will override any TransactionSigners associated with the WalletManager.

Parameters

deployer

The deployer instance to set, or null to clear the account.

null | TransactionSignerAccount

sync

boolean

A boolean indicating whether the account should be synchronized.

Returns

Store<TState>

Implementation of

StoreInterface.setAccount

---

setAlgorand()

setAlgorand(algorand): Store<TState>

Defined in: packages/store-kit/src/Store.ts:317

Binds the provided AlgorandClient to the current instance.

Parameters

algorand

AlgorandClient

Returns

Store<TState>

Implementation of

StoreInterface.setAlgorand

---

setAppId()

setAppId(appId, sync): Promise<Store<TState>>

Defined in: packages/store-kit/src/Store.ts:215

Sets the application ID for the store.

Parameters

appId

bigint

The application ID to associate with the store.

sync

boolean

Optionally trigger all lifecycle events, defaults to false

Returns

Promise<Store<TState>>

Implementation of

StoreInterface.setAppId

---

setClient()

setClient(client, sync): Promise<Store<TState>>

Defined in: packages/store-kit/src/Store.ts:328

Binds the provided LodashClient to the current instance.

Parameters

client

LodashClient

sync

boolean = true

Returns

Promise<Store<TState>>

---

setManager()

setManager(manager): Store<TState>

Defined in: packages/store-kit/src/Store.ts:237

Binds the provided WalletManager to the current instance. If the WalletManager has an active address, it initializes the deployer object using the active address and transaction signer. Additionally, sets up a subscription to handle state changes in the WalletManager.

Parameters

manager

The wallet manager instance to be bound.

null | WalletManager

Returns

Store<TState>

Implementation of

StoreInterface.setManager

---

toChunks()

toChunks(): (undefined | string)[][]

Defined in: packages/store-kit/src/Store.ts:432

Returns

(undefined | string)[][]

---

toMBR()

toMBR(): bigint

Defined in: packages/store-kit/src/Store.ts:226

Returns

bigint

---

toMBRDelta()

toMBRDelta(): Promise<bigint | 0>

Defined in: packages/store-kit/src/Store.ts:427

TODO: get delta and update MBR

Returns

Promise<bigint | 0>