@artblocks/abx-sdk 0.1.0-alpha.9 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,207 @@
+# @artblocks/abx-sdk
+
+## 0.2.0
+
+### Minor Changes
+
+- 7947ba9: Drop-in for read-only consumers. Hosts that serve stored images should adopt `storedImageType`.
+
+  On-chain raster images now display correctly. Stored `image` bytes are labelled with the new reserved
+  `abx_image_type` field, and fall back to `image/svg+xml` when it is unset. Before this change, a JPEG
+  or PNG staged with `--onchain-image` was served as SVG, which browsers show as a broken image.
+
+  - SDK: `METADATA_FIELD.imageType`, `storedImageType`, `isDeclarableImageType`, and
+    `DEFAULT_STORED_IMAGE_TYPE`. `isCurrentRenderer` now requires renderer spec v12, and the
+    canonical renderer address points at the v12 build.
+  - CLI: `deploy --onchain-image`, `deploy-series --onchain-image`, and `set-field --field image --file`
+    declare a raster's type from its file extension. They refuse formats browsers don't draw, such as
+    TIFF, PSD, video, and files without an extension, before anything is staged.
+  - Token API: the image route, the `/data/image` route, and the `artifacts` manifest serve the
+    declared type.
+
+## 0.1.0
+
+### Minor Changes
+
+- 21e3d6c: Drop-in for existing v2 integrations; new deployments use the canonical v3 contracts.
+  Record the synchronized v3 factory generation and testnet deployments, retain full v2 service
+  compatibility (including already-assigned v2 sale minters), and update the renderer scaffold to
+  `abx-contracts` 3.0.0.
+- 22abce8: Generalize the creator-wallet sponsorship lane to direct zero-value contract creation and
+  receipt-dependent on-chain image staging. Add `abx deploy-contract` for exact Foundry artifact or
+  initcode deployment through any signing lane.
+- ea57f7a: Add provider-neutral remote interface discovery, the ABX Creators account API client, and the Base
+  Sepolia creator-wallet `--sponsor` signing lane. A provider catalog may advertise its account and
+  wallet interfaces at a separate HTTPS origin without changing existing same-origin remotes.
+- 3ddba71: Drop-in for existing SDK callers; new consumers can inspect contract-generation compatibility.
+  Add the append-only generation registry, stable lookup helpers, and lifecycle and operation support
+  to provenance results.
+- 9065128: Drop-in for existing clients; service consumers can now inspect verified contract-generation facts.
+  Advertise understood generations and include a project generation in summaries and status responses
+  only when factory provenance and the on-chain core version agree.
+
+### Patch Changes
+
+- 4d5e2b1: Return minimal metadata for unminted token positions and keep their image, data, and live-view URLs unavailable until mint.
+- 56973c4: Preserve `maxInvocations` as an exact uint256 value instead of narrowing it through a JavaScript
+  number. Reuse an existing hosted-service credential on login and add self-service API-key listing
+  and revocation for accounts at their active-key limit.
+- 2290b0a: Recover ambiguous creator-wallet submissions through the existing operation status instead of replaying them. Sponsored sends now keep polling safely when the provider response is temporarily unknown and surface the operation ID if reconciliation cannot complete.
+- b9197bc: Record the exact-match canonical Robinhood Chain production deployment while keeping the network
+  disabled until its services and low-value acceptance gates pass.
+- 8ccbede: Enable Robinhood Chain production as beta after canonical deployment, paired-testnet qualification,
+  and managed-service validation. Surface the same real-funds warning and testnet-first gate used for
+  other production beta networks.
+- d925eb1: Breaking only for SDK callers that directly prepared an unsupported sponsored `to: null` request;
+  drop-in for existing hot, wallet, and unsigned deployments. Route sponsored custom-contract
+  deployments through ABX's existing keyless CREATE2 proxy, expose the exact signer-bound salt and
+  predicted address, verify code after confirmation, and document the proxy constructor-caller boundary.
+- 8f35dae: Prepare package metadata, release notes, and public-facing source comments for the initial public
+  source release.
+- 719b9fe: Make the bundled skill read network and sponsorship support from CLI capabilities and the live
+  service descriptor instead of a hardcoded network list. Refresh public documentation references in
+  the published packages.
+- c2400a7: Stage Robinhood Chain and its testnet as disabled qualification targets, keep the network registry
+  focused on the current roadmap, and stop sale inspection from turning RPC read failures into false
+  zero-state results.
+- 3d7fe3c: Record the verified canonical Robinhood Chain Testnet deployment and enable the network for
+  experimental qualification with explicit CLI and agent guidance.
+- 7b462e2: Update the SDK's Viem dependency to the latest compatible patch release.
+- ddb2e0b: Refuse irreversible URI locks when the current token or collection base uses `abx.io`. Clarify that
+  managed resolver URLs must remain mutable unless a creator-controlled domain is routed and verified.
+- 4512962: Enable Base production as beta, add a keyless read fallback, and surface production risk and paired-testnet guidance in the CLI, agent skill, and public docs.
+- 76cfc6a: Follow each remote service interface's advertised origin so provider catalogs can separate token data from account and control APIs.
+- 5522192: Record the source-verified Base production contract deployment while keeping Base disabled for CLI
+  use until the separate beta-enablement release.
+
+## 0.1.0-alpha.49
+
+### Patch Changes
+
+- 719b9fe: Make the bundled skill read network and sponsorship support from CLI capabilities and the live
+  service descriptor instead of a hardcoded network list. Refresh public documentation references in
+  the published packages.
+
+## 0.1.0-alpha.48
+
+### Patch Changes
+
+- 4d5e2b1: Return minimal metadata for unminted token positions and keep their image, data, and live-view URLs unavailable until mint.
+
+## 0.1.0-alpha.47
+
+### Patch Changes
+
+- 56973c4: Preserve `maxInvocations` as an exact uint256 value instead of narrowing it through a JavaScript
+  number. Reuse an existing hosted-service credential on login and add self-service API-key listing
+  and revocation for accounts at their active-key limit.
+
+## 0.1.0-alpha.46
+
+### Patch Changes
+
+- ddb2e0b: Refuse irreversible URI locks when the current token or collection base uses `abx.io`. Clarify that
+  managed resolver URLs must remain mutable unless a creator-controlled domain is routed and verified.
+- 76cfc6a: Follow each remote service interface's advertised origin so provider catalogs can separate token data from account and control APIs.
+
+## 0.1.0-alpha.45
+
+### Patch Changes
+
+- d925eb1: Breaking only for SDK callers that directly prepared an unsupported sponsored `to: null` request;
+  drop-in for existing hot, wallet, and unsigned deployments. Route sponsored custom-contract
+  deployments through ABX's existing keyless CREATE2 proxy, expose the exact signer-bound salt and
+  predicted address, verify code after confirmation, and document the proxy constructor-caller boundary.
+
+## 0.1.0-alpha.44
+
+### Minor Changes
+
+- 22abce8: Generalize the creator-wallet sponsorship lane to direct zero-value contract creation and
+  receipt-dependent on-chain image staging. Add `abx deploy-contract` for exact Foundry artifact or
+  initcode deployment through any signing lane.
+
+## 0.1.0-alpha.43
+
+### Patch Changes
+
+- 2290b0a: Recover ambiguous creator-wallet submissions through the existing operation status instead of replaying them. Sponsored sends now keep polling safely when the provider response is temporarily unknown and surface the operation ID if reconciliation cannot complete.
+
+## 0.1.0-alpha.42
+
+### Minor Changes
+
+- ea57f7a: Add provider-neutral remote interface discovery, the ABX Creators account API client, and the Base
+  Sepolia creator-wallet `--sponsor` signing lane. A provider catalog may advertise its account and
+  wallet interfaces at a separate HTTPS origin without changing existing same-origin remotes.
+
+## 0.1.0-alpha.41
+
+### Patch Changes
+
+- 8ccbede: Enable Robinhood Chain production as beta after canonical deployment, paired-testnet qualification,
+  and managed-service validation. Surface the same real-funds warning and testnet-first gate used for
+  other production beta networks.
+
+## 0.1.0-alpha.40
+
+### Patch Changes
+
+- b9197bc: Record the exact-match canonical Robinhood Chain production deployment while keeping the network
+  disabled until its services and low-value acceptance gates pass.
+
+## 0.1.0-alpha.39
+
+### Patch Changes
+
+- 3d7fe3c: Record the verified canonical Robinhood Chain Testnet deployment and enable the network for
+  experimental qualification with explicit CLI and agent guidance.
+- 7b462e2: Update the SDK's Viem dependency to the latest compatible patch release.
+
+## 0.1.0-alpha.38
+
+### Patch Changes
+
+- c2400a7: Stage Robinhood Chain and its testnet as disabled qualification targets, keep the network registry
+  focused on the current roadmap, and stop sale inspection from turning RPC read failures into false
+  zero-state results.
+
+## 0.1.0-alpha.37
+
+### Patch Changes
+
+- 4512962: Enable Base production as beta, add a keyless read fallback, and surface production risk and paired-testnet guidance in the CLI, agent skill, and public docs.
+
+## 0.1.0-alpha.36
+
+### Patch Changes
+
+- 5522192: Record the source-verified Base production contract deployment while keeping Base disabled for CLI
+  use until the separate beta-enablement release.
+
+## 0.1.0-alpha.35
+
+### Minor Changes
+
+- 21e3d6c: Drop-in for existing v2 integrations; new deployments use the v3 production-candidate contracts.
+  Record the synchronized v3 factory generation and testnet deployments, retain full v2 service
+  compatibility (including already-assigned v2 sale minters), and update the renderer scaffold to
+  `abx-contracts` 3.0.0.
+
+## 0.1.0-alpha.34
+
+### Minor Changes
+
+- 3ddba71: Drop-in for existing SDK callers; new consumers can inspect contract-generation compatibility.
+  Add the append-only generation registry, stable lookup helpers, and lifecycle and operation support
+  to provenance results.
+- 9065128: Drop-in for existing clients; service consumers can now inspect verified contract-generation facts.
+  Advertise understood generations and include a project generation in summaries and status responses
+  only when factory provenance and the on-chain core version agree.
+
+## 0.1.0-alpha.33
+
+### Patch Changes
+
+- 9242a05: Prepare package metadata, release notes, and public-facing source comments for the initial public
+  source release.

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).