Docs
Powered by

SDK reference

@artblocks/abx-sdk is the low-level TypeScript library above the contracts. It is ESM-only, built on viem, and requires Node 22.5 or newer.

Install

npm install @artblocks/abx-sdk viem
import { deployOneOfOne, reconstructProject, makePublicClient } from '@artblocks/abx-sdk';
import { oneOfOneImageAbi } from '@artblocks/abx-sdk/abi';

The SDK never takes custody of keys. It reads a signing key from the environment when it builds a wallet client, and stores nothing.

Clients

  • makePublicClient(opts?): a read-only client. Several RPC URLs become a viem fallback transport with immediate failover.
  • makeWalletClient(opts?): a signing client. It reads the private key from ABX_DEPLOYER_PK, then SEPOLIA_FUNDED_PK, then SEPOLIA_WALLET_PK, and throws if none is set.
  • assertChainId(chainKey?): check the connected network before a write, and fail on a mismatch.
  • envSigningKey(): read the environment signing key without building a client.

Chains

  • CHAINS: the supported chain targets, base-sepolia and sepolia.
  • DEFAULT_CHAIN_KEY: base-sepolia.
  • resolveRpcUrls(chainKey?): the ordered RPC list. A per-chain ABX_RPC_URLS_<CHAIN> wins, then ABX_RPC_URLS, then a built-in public default.

Deploy and predict

Infrastructure deploys, run once per chain: deployFactory, deploySeriesFactory, deploySeriesCodeFactory, deployRenderer, deployFixedPriceMinter, and deploySeedSource.

Project deploys:

  • deployOneOfOne(wallet, account, publicClient, { factory, params, salt }): deploy a 1/1 as an immutable clone at a deterministic address. params is a OneOfOneInitParams.
  • deploySeries(wallet, account, publicClient, { factory, params, salt }): deploy a multi-token Series. params is a SeriesInitParams.
  • predictClone(publicClient, { factory, salt }): compute a clone's address before deploying, so URIs can be set at deploy time.

Salts:

  • saltFor(deployer, entropy?): a salt whose guard prefix reserves the address to deployer.
  • permissionlessSalt(entropy?): a salt with no guard, for a shared canonical address.
  • saltGuard(salt): the address a salt reserves, or the zero address if permissionless.

Reconstruct

  • reconstructProject(client, { address, fromBlock, toBlock?, factory? }): rebuild a project's state by folding the event spine and reading string values at the head. Returns a ProjectState.
  • reconstructIncremental(client, prior, opts?): resume from a prior reconstruction's checkpoint and fetch only new blocks.
  • discoverDeployBlock(client, address, toBlock?): find a contract's deployment block.

A ProjectState includes the identity and trust fields (address, chainId, abxVersion, factory, isCanonical), the collection identity (name, symbol, owner, royalty), the URI resolution config, the on-chain metadata fields, the Series and code-project state where present, the enabled extensions, and per-token state.

Tokens

Helpers over a reconstructed ProjectState:

  • findToken(state, tokenId): the token, or null.
  • fieldOf(fields, fieldName): a field's active on-chain entry, or null.
  • isOnChain(representation): whether the content lives on-chain (inline or reader).
  • inlineText(field) and inlineBytes(field): decode an inline value.
  • verifyAgainstHash(bytes, field): check content against a keccak256 or sha256 field.

Deployments

DEPLOYMENTS holds the canonical addresses per chain: the factories, renderer, chunk store, fixed-price minter, seed source, and generator. The factory addresses are the trust anchor: a contract is canonical when the chain's factory deployed it, which reconstructProject reports as isCanonical. Resolver helpers such as resolveFactory, resolveRenderer, and resolveChunkStore follow an override, then environment variable, then manifest order. The alpha scope is testnet-only.

Spine

spine exposes the protocol vocabulary: EXTENSION_ID and EXTENSION_NAMES for the extensions, METADATA_FIELD and METADATA_REPRESENTATION for the metadata tags, PARAM_TYPES and AUTH_OPTIONS for configurable parameters, and the event catalog. It also provides the tag and parameter codecs.