@heyanon-arp/sdk 0.0.9 → 0.0.10

package/dist/assets.d.ts

@@ -1,27 +1,24 @@
 /**
- * Well-known asset shorthand table + CAIP-19 helpers.
+ * Payment asset whitelist + CAIP-19 helpers.
  *
  * The protocol carries assets as `AssetIdentifier` ({ asset_id, decimals,
- * symbol? }) with `asset_id` always a CAIP-19 string. Operators almost
- * always work with two assets — USDC and native SOL on either mainnet
- * or devnet — and typing 90-char CAIP-19 strings on every CLI call is
- * hostile. This module:
+ * symbol? }) with `asset_id` always a CAIP-19 string. Payment assets
+ * are a CLOSED per-cluster whitelist (mirroring the V2 contract's
+ * on-chain `CollateralConfig` allowlist):
  *
- *   1. Exports `WELL_KNOWN_ASSETS` — the four mainstream entries
- *      mapped from shorthand keys to canonical `AssetIdentifier`.
- *   2. Exports `resolveAsset(input)` — accepts either a shorthand key
- *      OR a raw CAIP-19 string. Shorthand resolves from the table;
- *      raw CAIP-19 is returned unchanged with `decimals: null`
- *      sentinel (caller must supply via separate flag/field).
- *   3. Exports `CAIP19_REGEX` — the validation regex (server-side and
- *      client-side both lean on the same source of truth).
+ *   - solana-mainnet: SOL, USDC, USDT, ANON
+ *   - solana-devnet:  SOL only
  *
- * V1 launch ships only the four shorthand entries — extending the
- * table is a SemVer-minor patch. Adding a Solana cluster (testnet?)
- * is one entry. Adding a different chain (Ethereum, Polygon) is two
- * entries (the native + USDC equivalent on that chain).
+ * This module is the single source of truth — the server's offer/lock
+ * gates and the CLI's shorthand resolution both import from here.
+ * Extending the list is one table entry (SemVer-minor). The server
+ * can additionally merge test-only entries via the
+ * `ARP_ASSET_WHITELIST_EXTRA` env (see server docs) — those are
+ * invisible to this static table by design.
  */
 import type { AssetIdentifier } from './types/body';
+/** Solana clusters the protocol deploys to. */
+export type SolanaCluster = 'solana-mainnet' | 'solana-devnet';
 /**
  * Solana cluster genesis-hash prefixes per CAIP-2 (`solana:<cluster_id>`).
  * The full genesis hash is 32 bytes; CAIP-2 uses the first 32 chars
@@ -44,19 +41,65 @@ export declare const SOLANA_CLUSTER_IDS: {
  */
 export declare const SLIP44_SOLANA = 501;
 /**
- * Canonical SPL mints for USDC across the two Solana clusters we
- * support at V1 launch. Source: Circle's official USDC documentation.
+ * Canonical mainnet SPL mints for the whitelisted tokens. Each was
+ * verified on-chain before listing (mint exists, decimals match,
+ * owner = legacy SPL Token program — Token-2022 mints are not
+ * supported by the escrow):
+ *
+ *   - USDC: Circle's official Solana issue
+ *   - USDT: Tether's official Solana issue
+ *   - ANON: HeyAnon (docs.heyanon.ai → Contracts)
+ */
+export declare const MAINNET_MINTS: {
+    readonly USDC: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
+    readonly USDT: "Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB";
+    readonly ANON: "9McvH6w97oewLmPxqQEoHUAv3u5iYMyQ9AeZZhguYf1T";
+};
+/**
+ * @deprecated Compatibility alias for the pre-whitelist public API.
+ * Devnet USDC is NOT a payable asset anymore (devnet pays in native
+ * SOL only) — this constant exists solely so existing imports keep
+ * compiling. Use `MAINNET_MINTS` / `ASSET_WHITELIST` instead.
  */
 export declare const USDC_MINTS: {
     readonly 'solana-mainnet': "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
     readonly 'solana-devnet': "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU";
 };
 /**
- * Shorthand → `AssetIdentifier`. Keys follow the pattern
- * `<TICKER>:<CLUSTER>` so a glance tells you both the asset and the
+ * The payment whitelist, keyed by cluster. Closed list — an offer in
+ * any other asset is rejected server-side
+ * (`DELEGATION_ASSET_NOT_ALLOWED`). Devnet deliberately pays in
+ * native SOL only; SPL flows are exercised there via the server's
+ * `ARP_ASSET_WHITELIST_EXTRA` test hatch.
+ */
+export declare const ASSET_WHITELIST: Readonly<Record<SolanaCluster, readonly AssetIdentifier[]>>;
+/**
+ * Shorthand → `AssetIdentifier`, derived from the whitelist. Keys
+ * follow `<TICKER>:<CLUSTER>` (e.g. `USDC:solana-mainnet`,
+ * `SOL:solana-devnet`) so a glance tells you both the asset and the
  * cluster.
  */
 export declare const WELL_KNOWN_ASSETS: Readonly<Record<string, AssetIdentifier>>;
+/**
+ * Lookup table keys exported for `--help` choices in the CLI.
+ */
+export declare const WELL_KNOWN_ASSET_KEYS: readonly string[];
+/** Whitelisted assets for one cluster (defensive copies). */
+export declare function listWhitelistedAssets(cluster: SolanaCluster): AssetIdentifier[];
+/**
+ * Reverse lookup: CAIP-19 `asset_id` → whitelist entry + its cluster
+ * and shorthand key. Returns `null` for anything not whitelisted.
+ */
+export declare function findAssetByAssetId(assetId: string): {
+    asset: AssetIdentifier;
+    cluster: SolanaCluster;
+    key: string;
+} | null;
+/**
+ * Membership check. With `cluster` the asset must be listed for THAT
+ * cluster; without it, listed for any cluster.
+ */
+export declare function isWhitelistedAssetId(assetId: string, cluster?: SolanaCluster): boolean;
 /**
  * CAIP-19 strict regex. Reused by:
  *   - Server-side envelope validation (rejects malformed `asset_id`)
@@ -82,20 +125,14 @@ export declare function isAssetIdentifier(value: unknown): value is AssetIdentif
  * Resolve a shorthand key OR raw CAIP-19 string to an `AssetIdentifier`.
  *
  * Returns:
- *   - shorthand match → full `AssetIdentifier` from the table
- *   - raw CAIP-19 match → `{ asset_id: input, decimals: NaN, symbol: undefined }`
+ *   - shorthand match → full `AssetIdentifier` from the whitelist
+ *   - raw CAIP-19 that IS whitelisted → the canonical entry (decimals
+ *     and symbol filled in)
+ *   - raw CAIP-19 not in the whitelist → `{ asset_id: input, decimals: NaN }`
  *     (caller MUST supply decimals separately — NaN is a loud signal,
- *     not a useful default)
+ *     not a useful default). The server will reject such assets at
+ *     offer time unless its deploy carries matching
+ *     `ARP_ASSET_WHITELIST_EXTRA` entries, so CLIs should warn.
  *   - neither → `null`
- *
- * The NaN-on-raw-input behaviour exists because decimals can't be
- * inferred from CAIP-19 alone — `slip44:501` is SOL (9 decimals) but
- * `slip44:60` is ETH (18 decimals) and we don't ship a coin-type
- * registry in V1. Callers using raw CAIP-19 are expected to pass
- * `--rate-decimals <N>` alongside.
  */
 export declare function resolveAsset(input: string): AssetIdentifier | null;
-/**
- * Lookup table keys exported for `--help` choices in the CLI.
- */
-export declare const WELL_KNOWN_ASSET_KEYS: readonly string[];

package/dist/escrow/condition-hash.d.ts

@@ -11,9 +11,9 @@ import type { AssetIdentifier } from '../types';
  *     caller pre-mapping.
  *
  * `amount` is intentionally NOT here — the concrete locked amount AND its
- * mint are bound at settlement via the digest (`buildReleaseDigest` binds
+ * mint are bound on-chain at lock time (create_lock binds
  * `amount` u64 + `mint` 32B) and on-chain in the Lock account. The
- * condition_hash binds the agreed TERMS (scope / pricing / currency), not
+ * condition_hash binds the agreed TERMS (scope / currency), not
  * the amount. (Settlement is always escrow in V1 — no `settlement_model`.
  * The per-unit rate card — `rateAmount` / `rateUnit` — is NOT bound either:
  * nothing enforces it, so it stays out of the subset.)
@@ -22,9 +22,16 @@ import type { AssetIdentifier } from '../types';
  * golden vectors in `condition-hash.test.ts` pin it.
  */
 export interface DelegationTermsSubset {
+    /**
+     * Domain/version tag baked INTO the hashed bytes. V2 dropped the
+     * pricing-model concept from the terms (flat is the protocol's only
+     * semantics, not a setting) — the tag guarantees a V2 hash can never
+     * collide with a V1 hash over otherwise-identical fields, and gives
+     * future term-set changes an explicit version knob.
+     */
+    v: 'arp-condition-v2';
     delegationId: string;
     scopeSummary: string;
-    pricingModel: string;
     currency?: AssetIdentifier;
 }
 /**
@@ -37,7 +44,6 @@ export interface DelegationTermsSubset {
 export interface DelegationTermsInput {
     delegationId?: string;
     scopeSummary?: string;
-    pricingModel?: string;
     currency?: AssetIdentifier;
     [other: string]: unknown;
 }

package/dist/escrow/create-lock.d.ts

@@ -1,4 +1,6 @@
 export declare const CREATE_LOCK_DISCRIMINATOR: Uint8Array<ArrayBuffer>;
+/** sha256("global:create_lock_native")[0..8] — the lamport-path variant. */
+export declare const CREATE_LOCK_NATIVE_DISCRIMINATOR: Uint8Array<ArrayBuffer>;
 export interface CreateLockArgs {
     /** 32-byte lock_id (deriveLockId output). */
     lockId: Uint8Array;
@@ -6,31 +8,31 @@ export interface CreateLockArgs {
     amount: bigint;
     /** 32-byte condition_hash (deriveDelegationConditionHash output). */
     conditionHash: Uint8Array;
-    /** u64 unix-seconds expiry. */
-    expiry: bigint;
 }
 /**
- * Encode the create_lock instruction data: 8-byte disc +
- * Borsh-encoded `CreateLockParams { lock_id, amount, condition_hash,
- * expiry }`. Total 88 bytes — caller wraps in a TransactionInstruction
- * with the matching 11-account meta list (payer, payee, config, lock,
- * mint, payer_token_account, escrow_account, system_program,
- * token_program, event_authority, program).
+ * Encode the create_lock / create_lock_native instruction data:
+ * 8-byte disc + Borsh-encoded `CreateLockParams { lock_id, amount,
+ * condition_hash }`. Total 80 bytes. Both variants share the SAME
+ * params struct — only the discriminator and the account list differ
+ * (pass `native: true` for the lamport path).
  *
- * The new contract (Anchor 0.32.1 + `#[event_cpi]`) dropped:
- *   - `is_native_sol` bool — native SOL is signalled by
- *     `mint == Pubkey::default()` (all-zero pubkey) in the mint
- *     slot of the account list, NOT by a flag in the args.
- *   - Caller-supplied bumps for `lock` / `vault` / `vault_authority`
- *     — Anchor reads the bumps from `ctx.bumps` itself, and the old
- *     `vault` + `vault_authority` PDAs are replaced by a single
- *     `escrow_account` PDA derived from `[b"escrow", lock_id]`.
+ * There is NO expiry argument: `Lock.expiry` is a rolling deadline
+ * the chain derives from the Config windows on later transitions
+ * (`accept_lock` → work window, `submit_work` → review window,
+ * `open_dispute` → dispute window).
  *
- * SDK callers that still pass the old fields will hit a clear TS
- * compile error from the narrower `CreateLockArgs` shape — easier
- * to migrate than a silently-wrong tx.
+ * Account lists the caller assembles around this data:
+ *   create_lock (SPL, 12): payer, payee, config, lock,
+ *     collateral_config([b"collateral", mint]), mint,
+ *     payer_token_account, escrow_account, system_program,
+ *     token_program, event_authority, program.
+ *   create_lock_native (9): payer, payee, config, lock,
+ *     collateral_config([b"collateral", [0u8;32]]), escrow_account,
+ *     system_program, event_authority, program.
  */
-export declare function buildCreateLockIxData(args: CreateLockArgs): Uint8Array;
+export declare function buildCreateLockIxData(args: CreateLockArgs, opts?: {
+    native?: boolean;
+}): Uint8Array;
 /**
  * Sanity check: confirm the hard-coded discriminator matches what
  * sha256("global:create_lock")[0..8] should produce. Exposed for the

package/dist/escrow/index.d.ts

@@ -1,4 +1,6 @@
 export { deriveLockId, delegationIdToBytes16, bytes16ToDelegationId } from './lock-id';
 export { deriveDelegationConditionHash, type DelegationTermsSubset, type DelegationTermsInput } from './condition-hash';
 export { parseCaip19SolanaAssetId, type ParsedSolanaAssetId } from './caip19';
-export { buildCreateLockIxData, computeCreateLockDiscriminator, CREATE_LOCK_DISCRIMINATOR, type CreateLockArgs, } from './create-lock';
+export { buildCreateLockIxData, computeCreateLockDiscriminator, CREATE_LOCK_DISCRIMINATOR, CREATE_LOCK_NATIVE_DISCRIMINATOR, type CreateLockArgs, } from './create-lock';
+export { ESCROW_PDA_SEEDS, NO_ARG_LIFECYCLE_INSTRUCTIONS, type NoArgLifecycleInstruction, instructionDiscriminator, buildLifecycleIxData, buildResolveDisputeIxData, type ResolveDisputeArgs, } from './lifecycle-instructions';
+export { LOCK_ACCOUNT_SIZE, LOCK_ACCOUNT_DISCRIMINATOR, LOCK_STATE_NAMES, LOCK_TERMINAL_STATES, NATIVE_SOL_MINT_BASE58, type LockStateName, type DecodedLockAccount, decodeLockAccount, computeLockAccountDiscriminator, } from './lock-account';

package/dist/escrow/lifecycle-instructions.d.ts

@@ -0,0 +1,45 @@
+/** PDA seed strings of the V2 program, verbatim from the pinned IDL. */
+export declare const ESCROW_PDA_SEEDS: {
+    readonly LOCK: "lock";
+    readonly ESCROW: "escrow";
+    readonly CONFIG: "config";
+    readonly STAKE_VAULT: "stake_vault";
+    readonly COLLATERAL: "collateral";
+    readonly DISPUTE_RESOLUTION: "dispute_resolution";
+    readonly OPERATOR_AUTH: "operator_auth";
+    readonly EVENT_AUTHORITY: "__event_authority";
+};
+/**
+ * Lifecycle instructions whose data is the bare 8-byte discriminator
+ * (no Borsh args — the program reads the Lock account instead).
+ */
+export declare const NO_ARG_LIFECYCLE_INSTRUCTIONS: readonly ["accept_lock", "submit_work", "claim_work_payment", "claim_work_payment_native", "cancel_lock", "cancel_lock_native", "claim_expired_work", "claim_expired_work_native", "open_dispute", "close_dispute", "close_dispute_native"];
+export type NoArgLifecycleInstruction = (typeof NO_ARG_LIFECYCLE_INSTRUCTIONS)[number];
+/**
+ * Anchor instruction discriminator: `sha256("global:<name>")[0..8]`.
+ * Computed (not hardcoded) so a typo'd name can never silently drift
+ * from the on-chain program — the IDL sha-pin on the server side
+ * guards the other end.
+ */
+export declare function instructionDiscriminator(ixName: string): Uint8Array;
+/**
+ * Instruction data for the no-arg lifecycle instructions: exactly the
+ * 8-byte discriminator.
+ */
+export declare function buildLifecycleIxData(ixName: NoArgLifecycleInstruction): Uint8Array;
+export interface ResolveDisputeArgs {
+    /** true → escrow goes to the payer; false → to the payee. */
+    isPayerWinner: boolean;
+    /** 32-byte sha256 of the operator's resolution reasoning. */
+    reasonHash: Uint8Array;
+    /** 16-byte dispute id (the `dis_<uuid>` bytes). */
+    disputeId: Uint8Array;
+}
+/**
+ * Instruction data for resolve_dispute / resolve_dispute_native:
+ * 8-byte disc + Borsh `ResolveDisputeParams { is_payer_winner: bool,
+ * reason_hash: [u8;32], dispute_id: [u8;16] }`. Total 57 bytes.
+ */
+export declare function buildResolveDisputeIxData(args: ResolveDisputeArgs, opts?: {
+    native?: boolean;
+}): Uint8Array;

package/dist/escrow/lock-account.d.ts

@@ -0,0 +1,48 @@
+export declare const LOCK_ACCOUNT_SIZE = 269;
+/** sha256("account:Lock")[0..8] — pinned, verified by the test suite. */
+export declare const LOCK_ACCOUNT_DISCRIMINATOR: Uint8Array<ArrayBuffer>;
+/**
+ * On-chain `LockState` enum, discriminant order = array index.
+ * Mirrors the server's `EscrowLockState` strings 1:1.
+ */
+export declare const LOCK_STATE_NAMES: readonly ["created", "canceled", "in_progress", "submitted", "paid", "revoked", "disputing", "dispute_resolved", "dispute_closed"];
+export type LockStateName = (typeof LOCK_STATE_NAMES)[number];
+/** Terminal lock states — no further on-chain transition exists. */
+export declare const LOCK_TERMINAL_STATES: readonly LockStateName[];
+/** The contract's native-SOL sentinel mint, base58 form of [0u8;32]. */
+export declare const NATIVE_SOL_MINT_BASE58 = "11111111111111111111111111111111";
+export interface DecodedLockAccount {
+    /** Bare hex64. */
+    lockId: string;
+    version: number;
+    /** Base58. */
+    payer: string;
+    payee: string;
+    /** u64 base units. */
+    amount: bigint;
+    /** Base58; `NATIVE_SOL_MINT_BASE58` for native locks. */
+    mint: string;
+    /** True when `mint` is the all-zero sentinel. */
+    isNative: boolean;
+    /** Bare hex64. */
+    conditionHash: string;
+    /** Unix seconds; 0n while `created` (rolling deadline unset). */
+    expiry: bigint;
+    state: LockStateName;
+    stateByte: number;
+    feeBpsAtLock: number;
+    feeRecipientAtLock: string;
+    workerStakeAtLock: bigint;
+    operatorDisputeFeeAtLock: bigint;
+    treasuryAtLock: string;
+    bump: number;
+}
+/**
+ * Decode a fetched Lock account. Throws on size/discriminator/state
+ * mismatches — those mean the caller fetched the wrong account or the
+ * deployed program drifted from the pinned layout, and a loud error
+ * beats silently-wrong fields.
+ */
+export declare function decodeLockAccount(data: Uint8Array): DecodedLockAccount;
+/** Test hook: the canonical discriminator computation. */
+export declare function computeLockAccountDiscriminator(): Uint8Array;

package/dist/index.d.ts

@@ -7,11 +7,10 @@
  *   - keys         — Ed25519 generate/sign/verify, base58btc encoding
  *   - did          — `did:arp:<...>` parse/format + DID document types
  *   - envelope     — sign / verify envelope (steps 4-6 of protocol verification)
- *   - cosignature  — receipt + dispute-response co-signatures
  *   - challenge    — ARP-CHALLENGE-v1 ownership proof (registration)
  *   - attestation  — scrypt key-link owner attestation
  *   - server-chain — signed_message_hash, server_event_hash, audit walker
- *   - settlement   — ARP-SOLANA-* digest stubs (V1.5)
+ *   - settlement   — token-program detection (native + legacy SPL)
  *   - purpose      — domain separators (`ARP-*-v1`)
  *   - utils        — uuid v4, sender_nonce, RFC 3339, expires_at
  *   - types        — wire-level TypeScript types (Envelope, body union, identity)
@@ -24,7 +23,6 @@ export * from './canonical';
 export * from './keys';
 export * from './did';
 export * from './envelope';
-export * from './cosignature';
 export * from './challenge';
 export * from './attestation';
 export * from './server-chain';