@ar.io/sdk 4.0.0-alpha.1 → 4.0.0-alpha.2

package/README.md

@@ -18,6 +18,7 @@ supplied by [`@ar.io/solana-contracts`](https://www.npmjs.com/package/@ar.io/sol
 - [Usage](#usage)
 - [ARIO Contract](#ario-contract)
 - [ANT Contracts](#ant-contracts)
+- [Escrow](#escrow)
 - [Token Conversion](#token-conversion)
 - [Logging](#logging)
 - [Pagination](#pagination)
@@ -1996,6 +1997,40 @@ const observers = await ario.getPrescribedObservers({ epochIndex: 0 });
 
 </details>
 
+#### `crankEpochStep(options?)`
+
+High-level, permissionless epoch crank. Advances the epoch lifecycle by **one
+step per call** and returns the action it took — run it on a loop (this is what
+the standalone cranker and the observer-embedded cranker do). It owns the whole
+sequence so you don't orchestrate the individual instructions yourself:
+
+`create` → `tally` → `prescribe` → `distribute` → `close` — closing an epoch's
+observation PDAs first (`close_observation`) so `close_epoch` doesn't revert —
+plus an idle-tail of permissionless maintenance: `compound` delegate rewards,
+`update_demand_factor`, and `prune_returned_names`. The close path is
+non-wedging: a cleanup failure never blocks creation of the next epoch.
+
+```typescript
+const ario = ARIO.init({ rpc, rpcSubscriptions, signer });
+
+// one step
+const result = await ario.crankEpochStep();
+// → { action, epochIndex?, txId?, progress? }
+//   action ∈ create | tally | prescribe | distribute | close
+//          | close_observation | compound | update_demand_factor
+//          | prune_returned_names | idle
+
+// or drive it on an interval
+setInterval(async () => {
+  const r = await ario.crankEpochStep();
+  if (r.action !== 'idle') console.log(r.action, r.epochIndex, r.txId);
+}, 60_000);
+```
+
+All options are optional: `batchSize`, `enableClose`, `epochRetention`,
+`enableCompound`, `compoundMinPendingRewards`, `enableDemandFactorRoll`,
+`enablePrune`, `pruneBatchSize`, `nameRegistryAccount`.
+
 ### Primary Names
 
 #### `getPrimaryNames({ cursor, limit, sortBy, sortOrder })`
@@ -3026,6 +3061,57 @@ forking + name reassignment). On Solana, schema migration is a
 per-asset CPI exposed as the instance method `ant.upgrade()` documented
 above; new ANTs are created with `ANT.spawn()`.
 
+## Escrow
+
+Trustless, multi-protocol escrow for handing an asset to a recipient identified by
+an **Arweave** or **Ethereum** address, claimable once they hold a Solana wallet.
+Backed by the `ario-ant-escrow` program. Two clients:
+
+- `TokenEscrow` — escrow liquid **ARIO** (SPL) or a **time-locked vault**.
+- `ANTEscrow` — escrow an **ANT** (Metaplex Core NFT).
+
+Each supports **deposit → claim → cancel/refund → update-recipient**. Claims work
+three ways: **Arweave-attested** (an off-chain attestor re-signs the canonical
+claim with Ed25519, verified on-chain), **Ethereum** (on-chain `secp256k1_recover`
++ EIP-191), and **vault** (instruction introspection that preserves the remaining
+lock).
+
+```typescript
+import { TokenEscrow, canonicalMessageV2 } from '@ar.io/sdk';
+
+const escrow = new TokenEscrow({
+  rpc,
+  rpcSubscriptions,
+  signer,
+  programId,
+  coreProgram,
+});
+
+// deposit 50 ARIO to an Ethereum recipient
+await escrow.depositTokens({
+  assetId, // 32-byte client-supplied id
+  amount: 50_000_000n,
+  arioMint,
+  depositorTokenAccount,
+  recipient: { protocol: 'ethereum', publicKey: ethAddress20 },
+});
+
+// the recipient claims (Ethereum path) once they have a Solana wallet
+await escrow.claimTokensEthereum({
+  depositor,
+  assetId,
+  claimant,
+  claimantTokenAccount,
+  escrowTokenAccount,
+  signature, // recipient's EIP-191 signature over canonicalMessageV2(...)
+});
+```
+
+Build the exact bytes a recipient signs with `canonicalMessage` /
+`canonicalMessageV2` — byte-identical to the on-chain program (and the off-chain
+attestor). See the contracts repo's escrow design + protocol spec for the full
+flow and the cross-language canonical-message vectors.
+
 ## Token Conversion
 
 The ARIO process stores all values as mARIO (micro-ARIO) to avoid floating-point arithmetic issues. The SDK provides an `ARIOToken` and `mARIOToken` classes to handle the conversion between ARIO and mARIO, along with rounding logic for precision.
@@ -3258,7 +3344,7 @@ import {
 
 | Network | RPC | Programs |
 |---|---|---|
-| Mainnet | not yet deployed | TBD |
+| Mainnet | `https://api.mainnet-beta.solana.com` (mainnet-beta, default) | Not yet deployed — placeholder IDs in `src/solana/constants.ts` |
 | Devnet | `https://api.devnet.solana.com` | See `src/solana/constants.ts` for current devnet program IDs |
 | Localnet | Surfpool — `https://github.com/solana-foundation/surfpool` | Localnet harness in `solana-ar-io` monorepo |
 

package/lib/esm/cli/commands/antCommands.js

@@ -24,7 +24,7 @@ export async function setAntRecordCLICommand(o) {
     if (!o.skipConfirmation) {
         await assertConfirmationPrompt(`Are you sure you want to set this record on the ANT process ${writeAnt.processId}?\n${JSON.stringify(recordParams, null, 2)}`, o);
     }
-    return (await writeANTFromOptions(o)).setRecord(recordParams, customTagsFromOptions(o));
+    return writeAnt.setRecord(recordParams, customTagsFromOptions(o));
 }
 export async function setAntBaseNameCLICommand(o) {
     const ttlSeconds = +(o.ttlSeconds ?? defaultTtlSecondsCLI);
@@ -40,7 +40,7 @@ export async function setAntBaseNameCLICommand(o) {
     if (!o.skipConfirmation) {
         await assertConfirmationPrompt(`Are you sure you want to set this base name on the ANT process ${writeAnt.processId}?\n${JSON.stringify(params, null, 2)}`, o);
     }
-    return (await writeANTFromOptions(o)).setBaseNameRecord(params, customTagsFromOptions(o));
+    return writeAnt.setBaseNameRecord(params, customTagsFromOptions(o));
 }
 export async function setAntUndernameCLICommand(o) {
     const ttlSeconds = +(o.ttlSeconds ?? defaultTtlSecondsCLI);
@@ -58,7 +58,7 @@ export async function setAntUndernameCLICommand(o) {
     if (!o.skipConfirmation) {
         await assertConfirmationPrompt(`Are you sure you want to set this undername on the ANT process ${writeAnt.processId}?\n${JSON.stringify(params, null, 2)}`, o);
     }
-    return (await writeANTFromOptions(o)).setUndernameRecord(params, customTagsFromOptions(o));
+    return writeAnt.setUndernameRecord(params, customTagsFromOptions(o));
 }
 export async function transferRecordOwnershipCLICommand(o) {
     const undername = requiredStringFromOptions(o, 'undername');
@@ -67,5 +67,5 @@ export async function transferRecordOwnershipCLICommand(o) {
     if (!o.skipConfirmation) {
         await assertConfirmationPrompt(`Are you sure you want to transfer ownership of "${undername}" to "${recipient}" on ANT process ${writeAnt.processId}?\n${JSON.stringify({ undername, recipient }, null, 2)}`, o);
     }
-    return (await writeANTFromOptions(o)).transferRecord({ undername, recipient }, customTagsFromOptions(o));
+    return writeAnt.transferRecord({ undername, recipient }, customTagsFromOptions(o));
 }

package/lib/esm/cli/commands/escrowCommands.js

@@ -192,12 +192,18 @@ export async function escrowClaimArweaveCLICommand(o) {
     if (sigBytes.length !== 512) {
         throw new Error(`signature file must be 512 bytes; got ${sigBytes.length}`);
     }
+    // RSA-PSS salt length: 0 is a valid value, so only reject NaN / negative /
+    // non-integer. An unset flag defaults to 32 (a full SHA-256 digest).
+    const saltLen = o.saltLen ? Number.parseInt(o.saltLen, 10) : 32;
+    if (!Number.isInteger(saltLen) || saltLen < 0) {
+        throw new Error(`--salt-len must be a non-negative integer (got '${o.saltLen}')`);
+    }
     const escrow = await writeEscrowFromOptions(o);
     const sig = await escrow.claimArweave({
         antMint: antFromOptions(o),
         claimant: address(o.claimant),
         signature: sigBytes,
-        saltLen: o.saltLen ? Number(o.saltLen) : 32,
+        saltLen,
     });
     return { signature: sig };
 }

package/lib/esm/cli/commands/gatewayWriteCommands.js

@@ -74,7 +74,7 @@ export async function leaveNetwork(options) {
             '\n\n' +
             'Are you sure you want to leave the AR.IO network?', options);
     }
-    return (await writeARIOFromOptions(options)).ario.leaveNetwork(customTagsFromOptions(options));
+    return ario.leaveNetwork(customTagsFromOptions(options));
 }
 export async function saveObservations(o) {
     const failedGateways = requiredStringArrayFromOptions(o, 'failedGateways');
@@ -232,18 +232,17 @@ export async function delegateStake(options) {
     return output;
 }
 export async function decreaseDelegateStake(options) {
-    const ario = await (await writeARIOFromOptions(options)).ario;
+    const { ario, signerAddress } = await writeARIOFromOptions(options);
     const { target, arioQuantity } = requiredTargetAndQuantityFromOptions(options);
     const instant = options.instant ?? false;
     if (!options.skipConfirmation) {
         // Verify the target gateway exists and look up delegation
-        const signerAddr = (await writeARIOFromOptions(options)).signerAddress;
         const targetGateway = await ario.getGateway({ address: target });
         if (targetGateway === undefined) {
             throw new Error(`Gateway not found: ${target}`);
         }
         // Find delegation to this gateway
-        const delegations = await ario.getDelegations({ address: signerAddr });
+        const delegations = await ario.getDelegations({ address: signerAddress });
         const delegation = delegations.items.find((d) => d.gatewayAddress === target && d.type === 'stake');
         if (!delegation) {
             throw new Error(`No active delegation found for you on gateway ${target}.`);
@@ -279,7 +278,7 @@ export async function decreaseDelegateStake(options) {
     return output;
 }
 export async function redelegateStake(options) {
-    const ario = await (await writeARIOFromOptions(options)).ario;
+    const { ario, signerAddress } = await writeARIOFromOptions(options);
     const params = redelegateParamsFromOptions(options);
     if (!options.skipConfirmation) {
         const targetGateway = await ario.getGateway({ address: params.target });
@@ -293,8 +292,7 @@ export async function redelegateStake(options) {
         if (sourceGateway === undefined) {
             throw new Error(`Source gateway not found: ${params.source}`);
         }
-        const signerAddr = (await writeARIOFromOptions(options)).signerAddress;
-        const delegations = await ario.getDelegations({ address: signerAddr });
+        const delegations = await ario.getDelegations({ address: signerAddress });
         const delegation = delegations.items.find((d) => d.gatewayAddress === params.source && d.type === 'stake');
         if (!delegation || delegation.balance < params.stakeQty.valueOf()) {
             const available = delegation?.balance ?? 0;

package/lib/esm/cli/commands/pruneCommands.js

@@ -3,9 +3,15 @@ async function getSolanaWriter(o) {
     const { ario } = await writeARIOFromOptions(o);
     return ario;
 }
-function parseMaxNames(o) {
+function parseMaxNames(o, fallbackCount) {
     const raw = o.max;
     if (raw === undefined) {
+        // When an explicit name list is supplied, derive the u8 batch size from
+        // it (capped at the on-chain max of 255) so callers don't have to also
+        // pass --max. Discovery paths (no explicit list) still require --max.
+        if (fallbackCount !== undefined && fallbackCount > 0) {
+            return Math.min(fallbackCount, 255);
+        }
         throw new Error('--max <count> is required (u8 batch size, 1-255)');
     }
     const n = Number(raw);
@@ -18,7 +24,7 @@ function parseMaxNames(o) {
 // ArNS prune
 // =========================================
 export async function pruneExpiredNamesCLICommand(o) {
-    const max = parseMaxNames(o);
+    const max = parseMaxNames(o, o.arnsRecords?.length);
     const ario = await getSolanaWriter(o);
     // If `--arns-records` wasn't provided, discover them via the readable's
     // helper. Cap at `max` so we never overshoot the ix's u8 batch parameter.
@@ -44,7 +50,7 @@ export async function pruneNameToReturnedCLICommand(o) {
     return ario.pruneNameToReturned({ name });
 }
 export async function pruneReturnedNamesCLICommand(o) {
-    const max = parseMaxNames(o);
+    const max = parseMaxNames(o, o.returnedNames?.length);
     const ario = await getSolanaWriter(o);
     let returned = o.returnedNames ?? [];
     if (returned.length === 0) {
@@ -129,13 +135,11 @@ export async function releaseVaultCLICommand(o) {
     // configured signer as the owner. The `--owner` flag is accepted as
     // documentation but ignored unless it matches the signer; fail loud if
     // it doesn't, so users don't think they can release someone else's vault.
-    const ario = await getSolanaWriter(o);
-    if (o.owner) {
-        const signerAddr = (await writeARIOFromOptions(o)).signerAddress;
-        if (o.owner !== signerAddr) {
-            throw new Error(`release-vault: --owner ${o.owner} does not match signer ${signerAddr}. ` +
-                `release_vault is owner-signed; use the owner's wallet to call it.`);
-        }
+    const { ario: arioWrite, signerAddress } = await writeARIOFromOptions(o);
+    const ario = arioWrite;
+    if (o.owner && o.owner !== signerAddress) {
+        throw new Error(`release-vault: --owner ${o.owner} does not match signer ${signerAddress}. ` +
+            `release_vault is owner-signed; use the owner's wallet to call it.`);
     }
     const vaultIdStr = requiredStringFromOptions(o, 'vaultId');
     const vaultId = vaultIdStr;

package/lib/esm/cli/utils.js

@@ -248,7 +248,7 @@ export function requiredAddressFromOptions(options) {
     if (address !== undefined) {
         return address;
     }
-    throw new Error('No address provided. Use --address or --wallet-file');
+    throw new Error('No address provided. Use --address, --wallet-file, or --private-key');
 }
 const defaultCliPaginationLimit = 10; // more friendly UX than 100
 export function paginationParamsFromOptions(options) {
@@ -583,16 +583,25 @@ export function fundFromFromOptions(o) {
 export function referrerFromOptions(o) {
     return o.referrer;
 }
+/** Largest value representable by an unsigned 64-bit integer (2^64 - 1). */
+const U64_MAX = (1n << 64n) - 1n;
 /** Parse `--withdrawal-id` from CLI options into a bigint. */
 export function withdrawalIdFromOptions(o) {
     if (o.withdrawalId === undefined)
         return undefined;
+    let id;
     try {
-        return BigInt(o.withdrawalId);
+        id = BigInt(o.withdrawalId);
     }
     catch {
         throw new Error(`Invalid --withdrawal-id: '${o.withdrawalId}' is not a valid u64 integer`);
     }
+    // The on-chain seed encoder treats the id as a u64; reject out-of-range
+    // values here with a clear message instead of a downstream encoder error.
+    if (id < 0n || id > U64_MAX) {
+        throw new Error(`Invalid --withdrawal-id: '${o.withdrawalId}' is outside u64 range (0..${U64_MAX})`);
+    }
+    return id;
 }
 /**
  * Parse `--funding-plan-json` into a `FundingSourceSpec[]`. Validates each
@@ -647,6 +656,9 @@ export function fundingPlanFromOptions(o) {
         if (amount <= 0n) {
             throw new Error(`--funding-plan-json[${idx}].amount must be > 0 (got ${e.amount})`);
         }
+        if (amount > U64_MAX) {
+            throw new Error(`--funding-plan-json[${idx}].amount '${e.amount}' exceeds u64 max (${U64_MAX})`);
+        }
         const out = {
             kind: e.kind,
             amount,
@@ -658,6 +670,16 @@ export function fundingPlanFromOptions(o) {
             if (e.kind !== 'delegation' && e.kind !== 'operatorStake') {
                 throw new Error(`--funding-plan-json[${idx}].gateway is only valid for kind 'delegation' or 'operatorStake' (got '${e.kind}')`);
             }
+            // The gateway is going to be used: confirm it actually decodes as a
+            // base58 Solana address. `address()` throws on malformed input, so a
+            // bad string fails the CLI here rather than deep in instruction
+            // building.
+            try {
+                address(e.gateway);
+            }
+            catch {
+                throw new Error(`--funding-plan-json[${idx}].gateway '${e.gateway}' is not a valid base58 Solana address`);
+            }
             out.gateway = e.gateway;
         }
         return out;

package/lib/esm/common/faucet.js

@@ -11,6 +11,12 @@ const DEFAULT_FAUCET_API_URL = 'https://faucet.ario.permaweb.services';
  * id today; will likely become a Solana mint pubkey).
  */
 export function createFaucet({ arioInstance, faucetApiUrl = DEFAULT_FAUCET_API_URL, processId, }) {
+    // The backend has no implicit default for `processId`; fail at the API
+    // boundary so callers get immediate feedback instead of an opaque HTTP
+    // error on the first faucet call.
+    if (typeof processId !== 'string' || processId.trim() === '') {
+        throw new Error('createFaucet: `processId` is required and must be non-empty');
+    }
     const faucet = new ARIOTokenFaucet({
         faucetUrl: faucetApiUrl,
         processId,

package/lib/esm/version.js

@@ -14,4 +14,4 @@
  * limitations under the License.
  */
 // AUTOMATICALLY GENERATED FILE - DO NOT TOUCH
-export const version = '4.0.0-alpha.1';
+export const version = '4.0.0-alpha.2';

package/lib/types/common/io.d.ts

@@ -44,6 +44,26 @@ export type ARIOConfig = {
 };
 export declare const DEFAULT_SOLANA_RPC_URL = "https://api.mainnet-beta.solana.com";
 export declare class ARIO {
+    /**
+     * Create an ARIO client bound to a Solana RPC transport.
+     *
+     * The return type is selected by the {@link ARIOConfig} you pass:
+     * - **Read-write** — when `signer` (a {@link SolanaSigner}) is provided. A
+     *   {@link SolanaRpcSubscriptions} client is then also required so
+     *   `@solana/kit`'s `sendAndConfirmTransaction` can await confirmations;
+     *   omitting it throws. Returns {@link ARIOWrite}.
+     * - **Read-only** — when `signer` is omitted. Returns {@link ARIORead}.
+     *
+     * Program-id overrides (`coreProgramId` / `garProgramId` / `arnsProgramId` /
+     * `antProgramId`) are required on any non-mainnet cluster (devnet, localnet,
+     * Surfpool); see {@link ARIOConfig}.
+     *
+     * @param config - RPC transport, optional signer/subscriptions, and
+     *   per-cluster program-id overrides.
+     * @returns {@link ARIOWrite} when a signer is supplied, otherwise
+     *   {@link ARIORead}.
+     * @throws If a signer is supplied without `rpcSubscriptions`.
+     */
     static init(config: ARIOConfig & {
         signer: SolanaSigner;
         rpcSubscriptions: SolanaRpcSubscriptions;

package/lib/types/version.d.ts

@@ -13,4 +13,4 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-export declare const version = "4.0.0-solana.40";
+export declare const version = "4.0.0-alpha.1";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ar.io/sdk",
-  "version": "4.0.0-alpha.1",
+  "version": "4.0.0-alpha.2",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ar-io/ar-io-sdk.git"