SDK

@artblocks/abx-sdk is the ESM-only TypeScript library under the CLI. It uses viem and requires Node.js 22.13 or newer.

Use the CLI for a person or coding agent at a terminal. Use the SDK inside applications, workers, and repeatable jobs.

Install

npm install @artblocks/abx-sdk viem

import {makePublicClient, reconstructProject} from '@artblocks/abx-sdk';

const client = makePublicClient({chainKey: 'base-sepolia'});
const project = await reconstructProject(client, {
  address: '0xYourContract',
  fromBlock: 12345678n,
});

The main entry is safe to bundle for browsers. Import @artblocks/abx-sdk/node only from Node code. That subpath contains .env loading.

Configuration

Pass explicit options when possible. SDK fallbacks include:

The SDK never loads .env through its main entry. A host may call loadDotEnv() from the Node subpath.

ABX ships independent keyless RPC fallbacks where they are available. Set a comma-separated ABX_RPC_URLS_<CHAIN> list for production workloads or your own provider. A submitted transaction hash is durable evidence: if a receipt read fails, check that hash before sending again.

Transactions

Write helpers return PreparedTx. The object contains the destination, calldata, value, chain ID, and a human summary. Your application decides how to simulate, batch, sign, and send it.

import {
  makePublicClient,
  makeWalletClient,
  makeHotSender,
  prepareSetRoyalty,
  runPrepared,
} from '@artblocks/abx-sdk';

const publicClient = makePublicClient({chainKey: 'base-sepolia'});
const {wallet, account} = makeWalletClient({chainKey: 'base-sepolia'});
const send = makeHotSender({wallet, account, publicClient});

await runPrepared([
  prepareSetRoyalty({
    contract: '0xYourContract',
    receiver: account.address,
    bps: 500,
    chainId: 84532,
  }),
], send);

Browser wallets, Safes, ERC-4337 accounts, and transaction queues can implement the same SendTx function. Do not use makeHotSender in browser code.

batchOps() combines compatible operations into same-contract multicalls. Cross-contract calls stay separate unless the signing account provides its own batching.

Deployments

High-level deployment functions include:

• deployOneOfOne, deploySeries, deployOneOfOneEdition, deployEditionImage, and deployEditionCode
• predictClone and guarded saltFor
• ensureFactory, ensureSeriesFactory, and the other canonical infrastructure checks

Factories create deterministic EIP-1167 clones. The deploy result includes the clone address, transaction hash, and block number.

The lower-level prepareDeploy* functions return unsigned transactions without sending.

Owner operations and sales

The prepare* family covers transfers, mints, URI configuration, fields, locks, royalties, supply, minters, parameters, code, dependencies, seeds, and transfer validators.

Sale helpers include:

• prepareConfigureSale and preparePurchase for ERC-721
• prepareConfigureSale1155 and preparePurchase1155 for editions
• readSaleConfig and readSaleConfig1155

Read and reconstruct

reconstructProject() replays the ABX event history and confirms live contract state. The result holds identity, ownership, token type, canonical status, URI configuration, fields, policy, code, parameters, and token rows.

For a watcher, use reconstructIncremental() with the previous state or reconstructFromLogs() with logs fetched by a shared process. getLogsAdaptive() handles RPC range limits.

Both reconstruction functions scan through latest by default. Pass toBlock: 'safe' or toBlock: 'finalized' to stop there. The SDK resolves the tag to a block number before scanning and stores that number in ProjectState.toBlock. If the RPC does not support the tag, the call throws BlockTagUnavailableError.

Other common reads:

ERC-721 lifecycle values are unminted, live, and terminal burned. ERC-1155 editions use live or no-live-copies; an ID with zero copies can mint again.

Resolver client

AbxServiceClient speaks the public service descriptor and version 1 control plane.

import {AbxServiceClient, isAccepted} from '@artblocks/abx-sdk';

const service = new AbxServiceClient({
  baseUrl: 'https://metadata.example.com',
  token: process.env.ABX_REMOTE_MYPROVIDER_TOKEN,
});

const result = await service.registerProject({
  chainId: 84532,
  address: '0xYourContract',
});

if (isAccepted(result)) {
  await service.awaitIndexed(84532, '0xYourContract');
}

The client also lists, removes, and reindexes projects and publishes effect status. See Hosted services.

Storage package

Byte storage lives in @artblocks/abx-storage. Its StorageBackend interface covers filesystem, S3/R2, IPFS, and Arweave. Install @artblocks/abx-storage-arweave to use the optional ArDrive Turbo uploader.

Use locatorStatus() or awaitLocatorReady() before placing a new locator in token metadata. An accepted upload may not be available through every gateway yet.

The package source and exported types are in packages/sdk.