# SDK reference

`@artblocks/abx-sdk` is the low-level TypeScript library above the contracts. It is ESM-only, built on
[viem](https://viem.sh), and requires Node 22.5 or newer.

## Install

```bash
npm install @artblocks/abx-sdk viem
```

```ts
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.