API at a glance
Every value crypto-aio exports, grouped by what you use it for, with a link to the page that explains it, and the types you use most. Every type is in the generated TypeDoc reference (below), and the API reports in etc/api/ list the whole public surface. test/docs/api-reference.test.ts checks that this page names every exported value and every handle method, so it cannot fall behind the code.
Entry points
| Import | What it has |
|---|---|
crypto-aio | The library: container, handle, model, errors, signers, stores, events, extension types |
crypto-aio/evm | evmChainPlugin for your own EVM chains, EVM constants, ethers and web3 client types |
crypto-aio/utxo | Bitcoin constants and the bitcoinjs-lib client type |
crypto-aio/tron | Tron constants and the tronweb client type |
crypto-aio/solana | Solana constants and the @solana/web3.js client type |
crypto-aio/ton | TON constants and the @ton/ton client type |
crypto-aio/avalanche | Avalanche constants and the @avalabs/avalanchejs client types |
crypto-aio/testing | The fake chain, fake time, scripted nodes, crash injection and store contract suites |
crypto-aio/native | native(), the escape hatch to a handle's SDK client (outside semver) |
The package is CommonJS with type declarations; require('crypto-aio') works as well as import, and so does Jest. The SDK client types (AvalancheNativeClient and the Sdk… interfaces, UtxoNativeClient) follow their SDK and are outside semver, as native() is.
The container: CryptoAio
| Member | Does | See |
|---|---|---|
new CryptoAio(options?) | A container: configuration, stores, signers, hooks, plugins, driver pool, event bus | Configuration |
aio.blockchain({ chain, … }) | A handle on this container | The big picture |
aio.scope(overrides) | A child container that inherits and overrides configuration, sharing pool and stores | Core concepts |
aio.use(plugin) | Registers a chain family plugin (root container only; repeatable) | Write a chain family plugin |
aio.on(type, handler), aio.onAny(handler) | Subscribe to events; each returns an unsubscribe function | Production architecture |
aio.operations.get(id), .list(filter?) | Read Operations of this namespace (filter: states, chain, network, limit) | The life of a transfer |
aio.operations.recover({ signal? }) | Startup recovery; returns { rebroadcast, checked, skipped, unresent, failed, reconciled } | Run workers and recover |
aio.monitor.start({ workerId?, signal?, batch? }) | Background workers until the signal aborts | Run workers and recover |
aio.monitor.runOnce({ workerId?, batch? }) | One worker pass; returns how many Operations it claimed | Run workers and recover |
aio.close() | Closes native clients and pooled drivers, stops workers; later calls throw INVALID_TRANSITION | Run workers and recover |
aio.namespace | The namespace that prefixes every store key | Configuration |
configure(options) sets up the default container, and defaultContainer() returns it; Blockchain.create({ chain, … }) makes a handle on it. Each configure() call merges its options into those of earlier calls, carries the stores over, and makes a new default container without closing the old one: call it once, at startup.
The handle: Blockchain
A handle is immutable and bound to one chain, network, library, provider set and wallet.
Identity and selection
| Member | Returns | Notes |
|---|---|---|
chain, network, library | The selection | Typed per chain |
config | A frozen, redacted snapshot of the resolved configuration | Secrets show as [REDACTED] |
capabilities, supports(capability) | The handle's capabilities | Capabilities |
with(overrides) | A new handle; this one is unchanged | Anything but chain |
ready() | this, once the SDK is loaded and providers verified | Call at startup |
limits() | { maxOutputs }, the driver's output limit | |
ext | The family's typed extras: bc.ext.evm, bc.ext.tron, … | Chains, families and drivers |
Addresses and assets
| Method | Returns | See |
|---|---|---|
validateAddress(text) | boolean | Wallets, keys and addresses |
normalizeAddress(text) | Address (or throws INVALID_ADDRESS) | Core concepts |
walletAddress(wallet?) | The Address of the handle's wallet, or of another configured wallet | |
deriveAddress(wallet, index) | A deposit Address from the wallet's xpub (hd-public-derivation) | |
addressFromPublicKey(publicKey, options?) | The chain's Address for a public key | |
resolveAsset(asset?) | AssetInfo for 'native', an alias such as 'USDC', a token ref or an asset id | Coins, tokens and amounts |
Reading
| Method | Returns | See |
|---|---|---|
getBalance(address, asset?) | Balance: { address, asset, amount } | |
getBalances(address, assets) | Balance[] | |
getBlockHeight() | The latest height, as bigint | |
getBlock(heightOrHash) | Block or null; its timestamp is Unix seconds on every family | |
getTransaction(id) | Transaction (status, transfers, fee, decoding, and block with its Unix-seconds timestamp) or null | Receive deposits |
getNetworkStatus() | { chain, network, height, finalizedHeight, endpoints, indexers } | Trust |
Sending
| Method | Returns | See |
|---|---|---|
estimateFee(intent) | FeeEstimate: { charges, bound, details }; feeTotal(estimate, assetId) sums one asset | Send a transfer |
transfer(intent, { idempotencyKey?, signal? }) | Submission: the Operation view plus wait(options) | Send a transfer |
prepareTransfer(intent, options?) | PreparedOperation: the Operation and its unsigned transaction with signing requests | Cold and asynchronous signing |
submitSignatures(operationId, signatures or signed payload) | Submission | Cold and asynchronous signing |
broadcast(raw) | The node's answer, for bytes signed elsewhere, without an Operation: no idempotency or monitoring | Prefer prepareTransfer |
A TransferIntent is { to, amount, asset?, fee?, memo?, from? }, or { outputs: [{ to, amount }, …], asset?, fee?, memo?, from? } for several outputs (batch-transfer). An amount (AmountInput) is a decimal string, base units as a bigint, or an Amount; a number is refused. fee is 'slow', 'normal' (the default), 'fast', or the family's override object. from, when given, must be the selected wallet's address; estimateFee also takes it in place of a wallet.
Following and fixing an Operation
| Method | Returns | See |
|---|---|---|
getOperation(operationId) | OperationView or null | The life of a transfer |
getTransactionStatus(ref) | One read of a TxStatus | Wait for confirmation |
waitForConfirmation(ref, { finality?, confirmations?, timeoutMs?, pollIntervalMs?, signal? }) | { status, operation? } | Wait for confirmation |
watch(ref, { pollIntervalMs?, signal? }) | An async iterable of { status, operation? } | Wait for confirmation |
rebroadcast(operationId) | Resends the active Attempt's stored bytes | Fix a stuck transfer |
replace(operationId, { fee }) | A replacement in the same slot (replace-fee) | Fix a stuck transfer |
cancel(operationId, { fee? }) | A conflicting cancel (cancel); wins only if it lands first | Fix a stuck transfer |
rebuild(operationId) | Re-issues a proven expired Operation (expiry and seqno chains) | Fix a stuck transfer |
abandon(operationId) | Ends an Operation before anything was signed | Fix a stuck transfer |
A ref is an Operation id, an Attempt ref (the transaction hash), or a transaction hash the monitor has observed; any other id is read as an unmanaged transaction.
Receiving
| Method | Returns | See |
|---|---|---|
scanner({ cursorKey, from?, mode?, filter?, reorgWindow?, pollIntervalMs?, signal? }) | An async iterable Scanner of block and rollback events, each with ack() | Receive deposits |
history(address, { cursor?, limit? }) | { items: Transaction[], next? } (address-history) | Receive deposits |
Signers and secrets
| Name | Does | See |
|---|---|---|
localSigner({ id?, secp256k1?, ed25519?, exportable? }) | A signer with keys in memory, from Secret keys | Keys, signers and secrets |
localSigner.generate({ curves, id?, exportable? }) | New keys: { signer, publicKeys } | |
localSigner.fromMnemonic(mnemonic, { id?, passphrase?, curves?, exportable? }) | A BIP39 signer from a Secret mnemonic; BIP32 for secp256k1, SLIP-10 for ed25519; paths from the wallet's keyRef | |
callbackSigner({ id, schemes, getPublicKey, sign, cancelRequest? }) | Any custody system as a signer; sign may answer pending | Keys, signers and secrets |
deriveXpubChild(xpub, path, versions?, network?) | A child public key from an extended public key | |
BUILTIN_SCHEMES | The signature schemes: secp256k1-ecdsa, secp256k1-schnorr, ed25519 | |
secret(value), reveal(value), isSecret(value), Secret, REDACTED | Wrap a credential so it prints as [REDACTED]; read it back explicitly | Secrets and redaction |
redactUrl(url), redactDeep(value) | Redact a URL, or every secret-like field of a value, for your own logs |
The model
| Name | Is | See |
|---|---|---|
Amount | An exact, non-negative quantity of one asset in base units: Amount.parse, Amount.from, Amount.fromBase, .base, .format(), .plus, .minus, .compare, .equals | Coins, tokens and amounts |
Address | A chain-bound address: .canonical, .display, .variant, .equals(), .format() | Wallets, keys and addresses |
assetId(chain, network, ref), parseAssetId(id) | Build and parse asset ids such as ethereum:mainnet/erc20:0x… | Core concepts |
feeTotal(estimate, assetId) | The total of one asset's charges in a fee estimate | Send a transfer |
explorerUrl(network, kind, id) | A block explorer link from a network's templates | |
KNOWN_CAPABILITIES | The built-in capability names | Capabilities |
Library | The built-in library names (ethers, web3, bitcoinjs-lib, …) | |
TERMINAL_STATES, NON_TERMINAL_STATES, isTerminal(state) | The Operation states that end, and those that don't | Core concepts |
mutuallyExclusive(a, b) | Whether two orderings conflict (only one can land) | Nonces, leases and many processes |
Errors
| Name | Is | See |
|---|---|---|
CryptoAioError | The base class: code, category, retryable, ambiguous, context, details, toJSON() | Errors |
ConfigError, UnsupportedCapabilityError, ValidationError, ProviderError, ChainError, SigningError, StateError, TimeoutError | One class per category | Errors |
isCryptoAioError(value) | A type guard | |
ERROR_CODES | Every code, with its category and default retryable flag | |
createError(code, message, options?) | Builds the right class for a code (for drivers and stores) |
Stores
| Name | Is | See |
|---|---|---|
createMemoryStores(clock?) | All four in-memory stores, for tests and single processes | Write a durable store |
MemoryOperationStore, MemoryLockManager, MemorySequenceStore, MemoryCursorStore | The in-memory stores, one by one | |
DATA_CLASSIFICATION | Every persisted field's class: sensitive, sensitive-until-broadcast, operational | Write a durable store |
CLEARABLE_FIELDS, OPERATION_PATCH_KEYS | The fields an Operation patch may set or clear | |
OPERATION_FORMAT | The record format this version stores Operations in; it reads every earlier one | Write a durable store |
stringifyTagged(value), parseTagged(text) | JSON that round-trips bigint and Uint8Array; stringifyTagged refuses a plain object that would read back as one | Write a durable store |
Events
aio.on(type, handler) delivers typed events, each with type and at. They carry operational data only: ids, states, codes, heights, timings and sizes.
| Event | Fires when |
|---|---|
rpc.request, rpc.response, rpc.error | The transport sends a request, gets an answer, or fails |
provider.health | After every completed health refresh, once per endpoint, with its state: healthy, lagging, open or disabled (never for unknown or half-open). A gauge, not a change event: compare with the last one to see a change |
provider.misconfigured | An endpoint serves another network |
provider.inconsistent | Endpoints disagree on a quorum read |
operation.state | An Operation moves from one state to another |
operation.stalled | A node refused a signed transfer |
attempt.state | An Attempt's status changes |
tx.reorged | A reorg moved or removed an observed transaction |
nonce.allocated, nonce.gap | A nonce or seqno is reserved; a nonce blocks later ones |
signer.requested, signer.completed | A signer is asked; it answers (signed, pending or error) |
scanner.block, scanner.rollback | A scanner delivers a block; rolls back |
recovery.skipped | recover() skipped an Operation that needs you |
createLogger(namespace, writer) builds a logger that redacts URLs and secret-like fields before your writer sees them; noopLogger discards everything. The default logger writes through debug: DEBUG=crypto-aio:*.
Extension points
For chain family plugins and drivers (Write a chain family plugin), the package exports the types Plugin, AdapterManifest, DriverFactory, DriverContext, ChainDriver and its ports, ChainInfo, NetworkInfo, ProviderPreset, AssetRegistration, SignatureScheme, Transport with its CallOptions and the store ports, and the value PLACEHOLDER_ORIGIN, the origin an SDK sees instead of a real URL. A driver's reads pass CallOptions: quorum: 'proof' for a proof read, and endpointLimit to mark a refusal as one endpoint's own limit (an indexer that will not scan a busy address), so a read without a quorum asks the endpoints it has not asked before the refusal stands. Family entry points add their own: evmChainPlugin, DEFAULT_MAX_FEE_PER_GAS, DEFAULT_MAX_GAS_LIMIT and EVM_CAPABILITIES (crypto-aio/evm); MAX_MEMO_BYTES, DEFAULT_EXPIRATION_MS, MIN_EXPIRATION_MS, MAX_EXPIRATION_MS, DEFAULT_MAX_FEE_LIMIT and DEFAULT_ENERGY_MARGIN_PERCENT (crypto-aio/tron); DEFAULT_MAX_COMPUTE_UNIT_PRICE (crypto-aio/solana); and each family's …_CAPABILITIES and …_PEER_DEPENDENCIES.
Types you use most
The types a caller names most often, beyond the values above:
| Type | Is |
|---|---|
AioOptions, ChainDefaults, ProviderConfig, EndpointConfig, WalletConfig, LifecycleOptions, TransportOptions, HandleOptions | The configuration shapes |
TransferIntent, AmountInput, FeeSpeed, FeeOverride, FeeEstimate, Submission, PreparedOperation | Sending (Send a transfer) |
OperationView, OperationState, TxStatus, TxState, TxFailure, WaitOptions | Following a transfer (Wait for confirmation) |
RecoveryReport | What recover() did: { rebroadcast, checked, skipped, unresent, failed, reconciled } |
Transaction, Transfer, Balance, Block, ScanEvent, ScannerOptions | Reading and receiving (Receive deposits) |
Signer, SigningRequest, SigningContext, Logger, LogWriter, Clock | The ports you implement for custody, logging and time |
ChainRegistry, FamilyRegistry, NativeClientMap | Registries a plugin augments, so its chains, families and native clients are typed (Write a chain family plugin) |
EvmChainPluginOptions (crypto-aio/evm) | What evmChainPlugin takes (Add a custom network) |
EvmFeeOverride, TronFeeDetails, UtxoWalletOptions, TonWalletIdentity, … | The shapes each family accepts or returns in its plain-record fields (Versioning and stability) |
The testing kit: crypto-aio/testing
| Name | Is | See |
|---|---|---|
createFakeEnv(options?) | A fake chain, a container and a funded handle, on fake time | Test with the fake chain |
FakeChain | The in-memory chain: mine, reorg, configureEndpoint, balance, nonce, sendCount, … | |
fakePlugin(), fakeManifest | The fake family: fakechain, fakeexpiry, fakeseqno | |
FakeClock, drive(clock, promise), settle | Time that moves only when you advance it | |
FakeFetch, rpcResult, rpcError, hang | A scripted HTTP server for testing drivers | |
FaultyOperationStore, CrashError | A store that "crashes the process" at a chosen write | Persistence and crash recovery |
describeOperationStoreContract, describeLockManagerContract, describeSequenceStoreContract, describeCursorStoreContract | The store contract suites, for Jest, Vitest or node:test | Write a durable store |
rejectsWithCode, SAMPLE_ORDERINGS, sampleOperation, sampleAttempt | Helpers for the contract suites | |
fakeAddress, isFakeAddress, fakeTxId, fakeDigest, signFake, encodeEnvelope, decodeEnvelope, REVERT_ADDRESS | The fake chain's own formats, for tests that build its data by hand; encodeEnvelope and decodeEnvelope are its wire protocol, outside semver (Versioning) |
The full type reference
The API reference has every type, with its documentation comments, for every entry point listed above. TypeDoc generates it from the source; after changing a doc comment or a signature, regenerate it with:
pnpm doc