@artblocks/abx-sdk 0.1.0-alpha.3 → 0.1.0-alpha.31

package/CHANGELOG.md

@@ -0,0 +1,79 @@
+# @artblocks/abx-sdk
+
+## 0.1.0-alpha.31
+
+### Minor Changes
+
+- c068a0f: Add `probeChunkStore` — a fail-closed sibling to `ensureChunkStore` that resolves whether a usable
+  on-chain chunk store exists (configured address, has code, answers the current `writeContent` ABI)
+  without ever sending a transaction or deploying one. Returns a typed verdict (`ok` / `unconfigured` /
+  `no-code` / `incompatible` / `unreachable`) instead of throwing, so a request-scoped or read-only
+  service can call it at startup and branch on the reason.
+- c068a0f: Local data-directory resolution (`.abx-self-host` / `ABX_DATA_DIR`) is now centralized in one SDK
+  resolver (`resolveDataDir` from `@artblocks/abx-sdk/node`) instead of five independent copies of the
+  same fallback across the CLI, indexer, and storage packages — the setup that could silently split a
+  project's SQLite projection from its managed Arweave key into two different directories.
+
+  A handful of READ commands (`status`, `state`, `verify`, `doctor`, `capabilities`, `tokens`,
+  `tokenuri`, `contracturi`, `inspect`, `minter show`) now search upward from the current directory,
+  git-style, for an already-existing `.abx-self-host` before falling back to creating one at cwd —
+  bounded at the home directory, a `.git` repository root, or the filesystem root, and never crossing
+  into an unrelated directory tree. Running one of these from a project subdirectory (e.g. a
+  `contracts/` folder) now finds the same node a run from the project root would, instead of quietly
+  reporting an empty one. `abx status`'s existing `data: <path>` line — and a new one-line notice —
+  name the directory whenever it was found this way. Every WRITE command is unaffected: it always
+  resolves strictly to the current directory, exactly as before, so nothing is ever created somewhere
+  you didn't `cd` into. `ABX_DATA_DIR`, when set, still always wins outright and disables the search
+  entirely.
+
+- c068a0f: `deploy-code --resume <address>` now works against an EditionCode (`--copies`) target, not just
+  SeriesCode. The mint leg diffs per id against that id's own `totalSupply(id)` — pass the same
+  content flags the original deploy used, plus `--mint-count`/`--mint-amount` if it premint any ids.
+- c068a0f: `reconstructProject()` and `reconstructIncremental()` accept `toBlock: 'safe' | 'finalized'` in
+  addition to a literal block number and the existing `'latest'` default. The tag is resolved to a
+  concrete inclusive block number (via the new `resolveBlockTag()`) before any `eth_getLogs` scan
+  starts, and that number — never the tag — is what lands in the persisted `ProjectState.toBlock`. An
+  RPC that doesn't support the requested tag throws the new `BlockTagUnavailableError` instead of
+  silently falling back to `latest`. `SelfHostIndexer#reindex` gained a matching `blockTag` option.
+  Existing callers (the `'latest'`/unset default) are unaffected.
+
+  `abx index --to-block safe|finalized` stops a re-index at a reorg-safe boundary.
+
+- c068a0f: Add `abx replace-script <address> --script <file>` — a safe, first-class way to replace an UNLOCKED
+  code project's on-chain program (`SeriesCode`/`EditionCode`, before `abx lock-script`). It refuses
+  outright on a locked script or a non-code target, diffs the replacement by content against what's
+  on-chain (an index that already matches is never re-sent), handles a smaller replacement by queuing
+  the trailing `removeLastScriptChunk` calls it needs, folds every write and remove into ONE atomic
+  transaction (a revert can never leave a half-applied script), and reads the completed script back to
+  verify it reassembles exactly to the file before reporting success. Supports `--dry-run` and every
+  signing lane.
+
+  The SDK gains the primitives this is built on: `prepareSetScriptChunk`/`prepareRemoveLastScriptChunk`
+  (no `prepare*` wrapper existed for `OnChainScript.sol`'s writers before this — every caller hand-
+  encoded `encodeFunctionData`), plus `planScriptReplace`/`verifyScriptReplace`, which take a small
+  reader interface (mirroring `resume.ts`'s own reader seam) so the diff and post-write verification
+  are testable without a chain.
+
+- c068a0f: Additive for SDK consumers — a new exported function, nothing existing changed shape or behavior.
+
+  `abx verify` now compares a collection's actual `tokenURIRenderer` and `animation_url` generator
+  pointers against the current canonical singletons for its chain, reporting each as current or
+  not-current (never treating an older-but-working deployment as broken). Adds the SDK helper
+  `isCurrentGenerator` alongside the existing `isCurrentRenderer` probe.
+
+### Patch Changes
+
+- c068a0f: `decodeReader` now requires the canonical `abi.encode(address reader, address pointer)`
+  shape — exactly two 32-byte words, each zero-padded — and rejects truncated, trailing-byte,
+  or double-encoded `reader` field values with an actionable error instead of silently
+  decoding a wrong address pair.
+
+## 0.1.0-alpha.30
+
+### Patch Changes
+
+- 64248d9: Establish the public source baseline and refresh dependency constraints.
+
+## Unreleased
+
+Public release history begins here.

package/README.md

@@ -0,0 +1,130 @@
+# @artblocks/abx-sdk
+
+The neutral, low-level TypeScript library for the ABX protocol — deploy, reconstruct from chain,
+resolve a token, verify content. It picks no provider, no UX, and (beyond a default chain target)
+no chain. Every ABX surface is built on this: the [`abx` CLI](https://docs.abx.io/docs/using-abx/installation)
+is a shell over it, the reference resolver reads through it, and a competing provider can import
+this same public library. If you're scripting one-off operations, the CLI is usually faster to
+reach for — install with `abx skill install` and let an agent drive it. Reach for the SDK when you're
+building something programmatic: a server, a mint endpoint, a scheduled job.
+
+ESM-only, built on [viem](https://viem.sh), requires Node 22.13+. The package's main entry is
+**browser-safe** — bundled and tested under `platform: 'browser'` on every change.
+
+## Install
+
+```bash
+npm install @artblocks/abx-sdk viem
+```
+
+```ts
+import { makePublicClient, ensureFactory, deployOneOfOne } from '@artblocks/abx-sdk';
+import { oneOfOneImageAbi } from '@artblocks/abx-sdk/abi';
+```
+
+## The send-injection model
+
+Every write returns a `PreparedTx` — unsigned, with a human-readable `summary`/`fields` for a sign
+page. The SDK never signs or broadcasts; it takes one function you provide:
+
+```ts
+type SendTx = (tx: PreparedTx) => Promise<TransactionReceipt>;
+```
+
+Every `deploy*`/`ensure*`/`prepare*`-and-execute function takes a `SendTx` as an argument, so how a
+transaction gets signed is entirely your call:
+
+- **`makeHotSender({ wallet, account, publicClient, onEvent? })`** — for an env/hot key. Pins the
+  nonce once (a distributed RPC can briefly serve a stale count right after a send, so it tracks the
+  nonce locally rather than re-reading it), detects an `eth_estimateGas` that came back impossibly
+  low (a sign the node hasn't seen a just-deployed target's code yet) and retries rather than sending
+  an under-funded transaction, and throws a typed `TxRevertedError` — never reports a burned,
+  reverted transaction as "confirmed."
+- **Bring your own** — a browser wallet, a Safe/multisig flow, a queue you drain later. Anything
+  that signs a `PreparedTx.data` and returns a `TransactionReceipt` works.
+
+Sequences: `runPrepared(txs, send)` sends a list in order. `batchOps(ops)` collapses same-target
+runs into one `Multicallable.multicall` transaction — several owner edits become one signature,
+all-or-nothing.
+
+## Worked example: deploy → upload → mint → read
+
+```ts
+import {
+  makePublicClient, makeWalletClient, makeHotSender,
+  ensureFactory, deployOneOfOne, saltFor, predictClone,
+  prepareMint, runPrepared, listTokens, reconstructProject, readSaleConfig,
+  encodeTag, type OneOfOneInitParams,
+} from '@artblocks/abx-sdk';
+import { resolveBackend, uploadAndLocate } from '@artblocks/abx-storage';
+import { zeroAddress, toHex } from 'viem';
+
+const publicClient = makePublicClient({ chainKey: 'base-sepolia' });
+const { wallet, account } = makeWalletClient({ chainKey: 'base-sepolia' }); // reads ABX_DEPLOYER_PK
+const send = makeHotSender({ wallet, account, publicClient });
+
+// 1. Deploy — resolve (or bootstrap) the chain's trust anchor, then deploy a clone.
+const factory = await ensureFactory(publicClient, send, { chainId: 84532 });
+const salt = saltFor(account.address); // front-run-proof: reserves the address to this signer
+const clone = await predictClone(publicClient, { factory, salt });
+
+// 2. Upload — put the image somewhere fetchable before baking its URL on-chain.
+const backend = resolveBackend({ backend: 'ipfs' }); // or 'cloud' / 'arweave' / 'fs'
+const bytes = new Uint8Array(/* … read your file … */);
+const { locator } = await uploadAndLocate(backend, 'art.png', { bytes, contentType: 'image/png' });
+
+const params: OneOfOneInitParams = {
+  owner: account.address,
+  mintTo: zeroAddress, // defer minting to step 3
+  name: 'My Piece', symbol: 'MYPC',
+  tokenURIBase: '', tokenURIRenderer: zeroAddress,
+  contractURIBase: '', contractURIRenderer: zeroAddress,
+  royaltyReceiver: account.address, royaltyBps: 500,
+  transferValidator: zeroAddress, // plain ERC-721; see ERC-721C in the site docs to opt in
+  tokenFields: [
+    // Bake the uploaded locator on-chain as the `image` field (an ipfs:// URI here; `arweave`/
+    // `url`/`keccak256` are the other off-chain representations — see the site docs for the choice,
+    // and `stageFieldContent` to put the bytes fully on-chain instead).
+    { field: encodeTag('image'), representation: encodeTag('ipfs'), value: toHex(locator) },
+  ],
+  contractFields: [],
+};
+const { txHash } = await deployOneOfOne(send, publicClient, { factory, params, salt });
+
+// 3. Mint — deploy deferred it (mintTo was the zero address), so mint explicitly.
+await runPrepared([prepareMint({ contract: clone, to: account.address, chainId: 84532 })], send);
+
+// 4. Read — straight from chain, no indexer required.
+const listing = await listTokens(publicClient, clone);              // owners, seeds, params
+const state = await reconstructProject(publicClient, {              // full protocol state
+  address: clone, fromBlock: (await publicClient.getBlockNumber()) - 100n,
+});
+```
+
+`encodeTag`/`decodeTag` (from the same package) turn a field name like `"image"` into the
+`bytes32` tag the contract expects — spelled out above only so the snippet is self-contained.
+Selling through the shared fixed-price minter is `prepareConfigureSale` + `preparePurchase` +
+`readSaleConfig(publicClient, minter, clone)` — see the [SDK reference](https://docs.abx.io/docs/reference/sdk)
+for the full surface (Series, code/generative projects, on-chain content staging, ERC-721C, and more).
+
+## Browser use
+
+The package's main entry (`.`) has **no Node-only imports** — it's bundled under
+`platform: 'browser'` and asserted clean of `node:*` resolution on every change. In a browser:
+
+- Pass `rpcUrls: [...]` explicitly to `makePublicClient`/`makeWalletClient` — there's no `process.env`
+  to fall back to, and the SDK never assumes one.
+- Sign with a connected wallet (build the `SendTx` yourself around it) rather than `makeHotSender`,
+  which expects a local `WalletClient` backed by a key.
+- **Never** import `@artblocks/abx-sdk/node` — that subpath is the *only* place `.env` loading lives
+  (`loadDotEnv`, needs `node:fs`/`node:path`) and it will break a browser bundle. A host (a CLI, a
+  server) calls `loadDotEnv()` once at startup; the SDK core just reads whatever's already in
+  `process.env` via a tiny `readEnv` that's a no-op outside Node.
+
+The only signing-key env var the SDK ever reads is `ABX_DEPLOYER_PK` (via `makeWalletClient`/
+`envSigningKey`) — and only as a *fallback* when you don't pass `privateKey`/`rpcUrls` explicitly.
+
+## More
+
+Full API documentation by task (deploy, sell, operate, read, embed in a browser, talk to a resolver)
+is in the [SDK reference](https://docs.abx.io/docs/reference/sdk).