@heyanon-arp/sdk 0.0.2

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

@@ -0,0 +1,79 @@
+import type { AssetIdentifier } from '../types';
+/**
+ * Subset of contract terms that the on-chain `condition_hash` binds.
+ * Chosen per the escrow design's "condition_hash semantics" decision:
+ * fields that the parties must agree on at offer time AND that the
+ * release flow must replay against. Excludes timestamps and
+ * decline-reason fields (those only exist on terminal rows; including
+ * them would make every accepted contract's hash dependent on
+ * non-content metadata).
+ *
+ * The shape MUST match server-side `deriveConditionHash` byte-for-byte;
+ * any drift breaks E5 settlement-digest reconstruction (which reads
+ * `condition_hash` from the on-chain Lock and expects it to equal a
+ * server-side recompute).
+ */
+export interface ContractTermsSubset {
+    contractId: string;
+    version: number;
+    scopeSummary: string;
+    pricingModel: string;
+    settlementModel: string;
+    rateAmount?: string;
+    rateCurrency?: AssetIdentifier;
+    rateUnit?: string;
+    allowedDelegationTags?: string[];
+}
+/**
+ * Loose input shape — the contract DTO / row / public response object
+ * may carry many extra fields (`state`, `relationshipId`, timestamps,
+ * decline reasons, etc.). Callers pass that whole object; we project
+ * onto `ContractTermsSubset` so extra fields can NEVER influence the
+ * condition_hash. This protects against silent drift if the public
+ * contract shape grows new fields.
+ *
+ * All fields are typed as optional here so a row pulled directly from
+ * Mongoose (where most contract fields are optional in the schema)
+ * fits the shape. The actual validity check happens inside
+ * `deriveConditionHash`, which throws if a required projected field
+ * is undefined — that surface is the right place to fail because
+ * `condition_hash` cannot be derived without it.
+ */
+export interface ContractLikeInput {
+    contractId?: string;
+    version?: number;
+    scopeSummary?: string;
+    pricingModel?: string;
+    settlementModel?: string;
+    rateAmount?: string;
+    rateCurrency?: AssetIdentifier;
+    rateUnit?: string;
+    allowedDelegationTags?: string[];
+    [other: string]: unknown;
+}
+/**
+ * Compute the 32-byte sha256 condition_hash that binds an on-chain
+ * lock to the off-chain contract terms.
+ *
+ * The function performs an EXPLICIT FIELD PROJECTION before
+ * canonicalisation. Even if the caller passes a full contract row
+ * with `state`, `createdAt`, `declineReason`, etc., only the eight
+ * whitelisted fields are hashed. This is critical for digest
+ * stability across SDK versions: adding a field to the public
+ * contract shape MUST NOT change `condition_hash` values for existing
+ * contracts.
+ *
+ * Wire procedure:
+ *   1. Project the caller's input onto the whitelisted subset.
+ *   2. JCS-canonicalize via the SDK's `canonicalBytes`.
+ *   3. sha256 → 32-byte digest.
+ *
+ * The same procedure runs on the server during `delegation.offer`
+ * validation AND during `receipt cosign` settlement-digest
+ * reconstruction. Any field-set drift between offer-time and
+ * cosign-time produces a different hash, which fails Ed25519 verify
+ * on-chain.
+ *
+ * @returns 32-byte condition_hash
+ */
+export declare function deriveConditionHash(contract: ContractLikeInput): Uint8Array;

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

@@ -0,0 +1,39 @@
+export declare const CREATE_LOCK_DISCRIMINATOR: Uint8Array<ArrayBuffer>;
+export interface CreateLockArgs {
+    /** 32-byte lock_id (deriveLockId output). */
+    lockId: Uint8Array;
+    /** u64 amount in base units. */
+    amount: bigint;
+    /** 32-byte condition_hash (deriveConditionHash 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).
+ *
+ * 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]`.
+ *
+ * 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.
+ */
+export declare function buildCreateLockIxData(args: CreateLockArgs): Uint8Array;
+/**
+ * Sanity check: confirm the hard-coded discriminator matches what
+ * sha256("global:create_lock")[0..8] should produce. Exposed for the
+ * SDK test suite; not used at runtime.
+ */
+export declare function computeCreateLockDiscriminator(): Uint8Array;

package/dist/escrow/index.d.ts

@@ -0,0 +1,4 @@
+export { deriveLockId, delegationIdToBytes16, bytes16ToDelegationId } from './lock-id';
+export { deriveConditionHash, type ContractTermsSubset, type ContractLikeInput } from './condition-hash';
+export { parseCaip19SolanaAssetId, type ParsedSolanaAssetId } from './caip19';
+export { buildCreateLockIxData, computeCreateLockDiscriminator, CREATE_LOCK_DISCRIMINATOR, type CreateLockArgs, } from './create-lock';

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

@@ -0,0 +1,67 @@
+/**
+ * Derive the on-chain `lock_id` (bytes32) from a wire-form delegation id.
+ *
+ * Decision baked into the escrow design: `lock_id = sha256("arp-lock-v1"
+ * || delegation_id_bytes16)`. Both parties can compute this without a
+ * round-trip:
+ *
+ *   - Payer derives it before submitting the offer (needs it to build
+ *     `create_lock` accounts: lock PDA, vault PDA, vault_auth PDA, all
+ *     seeded by `[<seed_prefix>, lock_id]`).
+ *   - Server derives it independently when validating the offer's
+ *     `attachments.escrow_lock.lock_id` claim.
+ *   - Payee derives it before cosigning the receipt (needs it to look up
+ *     the lock account and to feed into the settlement digest).
+ *
+ * Versioning: `"arp-lock-v1"` is a permanent literal. A future
+ * `arp-lock-v2` would derive different lock_ids for the same delegation,
+ * which is the right behaviour if we ever need to migrate seed shapes.
+ *
+ * @param delegationId — `del_<uuid>` string form (e.g. `del_550e8400-e29b-41d4-a716-446655440000`).
+ *                       The wire-form prefix is part of the hash input
+ *                       so this function takes raw strings, not bytes.
+ *                       BUT we hash the 16-byte UUID binary, NOT the
+ *                       string — see §"ID conversion" of the spec.
+ * @returns 32-byte lock_id
+ */
+export declare function deriveLockId(delegationId: string): Uint8Array;
+/**
+ * Convert a delegation id to the 16-byte representation the Solang
+ * contract takes as `bytes16 delegation_id`. RFC 4122 UUIDs are
+ * 128 bits = 16 bytes; the string form is 36 chars (32 hex + 4 dashes).
+ *
+ * Accepts BOTH wire-form variants the protocol uses:
+ *   - `del_<uuid>`  — SDK-canonical form (envelope SDK builders, server
+ *                     `LockValidatorService`, the wallet command's
+ *                     internal id pipeline).
+ *   - `<uuid>` bare — wire form for `body.content.delegation_id` (the
+ *                     ARP envelope canonical layout). All CLI / API
+ *                     callers pass bare here.
+ *
+ * Either way, the same 16-byte representation comes out (UUID body is
+ * the lock-id substrate; the `del_` prefix is a wrapper that exists
+ * only so the wire shape is unambiguously a delegation reference vs.
+ * a contract / receipt id elsewhere in the canonical JSON). Pushing
+ * this normalization down into the SDK gives every caller — CLI,
+ * server, future TypeScript clients — a single source of truth.
+ *
+ * Failure modes:
+ *   - UUID body doesn't match the canonical lowercase regex → throws
+ *     `Invalid delegation_id UUID` (canonical wire form is lowercase
+ *     per RFC 4122 §3; mixing cases would map two distinct strings
+ *     to the same on-chain `lock_id` — collision footgun).
+ *   - Empty / nonsense input → throws `Invalid delegation_id format`.
+ *
+ * Lowercase canonicalization is INTENTIONALLY preserved (not auto-
+ * downcased). The wire-format validator at the server already enforces
+ * lowercase; the strict check here is the second line of defence so
+ * two distinct wire strings cannot collide on the same lock_id.
+ */
+export declare function delegationIdToBytes16(delegationId: string): Uint8Array;
+/**
+ * Reverse of `delegationIdToBytes16` — render a 16-byte UUID back to
+ * the wire form `del_<canonical lowercase uuid>`.
+ *
+ * Output dash positions (8-4-4-4-12) match RFC 4122 §3 canonical form.
+ */
+export declare function bytes16ToDelegationId(bytes: Uint8Array): string;

package/dist/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * `@heyanon-arp/sdk` — Reference TypeScript implementation of the
+ * Agent Relationship Protocol (ARP) wire format.
+ *
+ * Module map:
+ *   - canonical    — RFC 8785 JCS, sha256 helpers, signing-input bytes
+ *   - 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 / rotation)
+ *   - webhook      — ARP-WEBHOOK-v1 HMAC header (outbox delivery)
+ *   - attestation  — scrypt key-link + key-rotation attestations
+ *   - server-chain — signed_message_hash, server_event_hash, audit walker
+ *   - settlement   — ARP-SOLANA-* digest stubs (V1.5)
+ *   - purpose      — domain separators (`ARP-*-v1`)
+ *   - utils        — uuid v4, sender_nonce, RFC 3339, expires_at
+ *   - types        — wire-level TypeScript types (Envelope, body union, identity)
+ *
+ * Server-side concerns (replay defence, time window, chain assignment,
+ * inbox policy) are NOT in this SDK — they are application-layer
+ * responsibilities of the backend.
+ */
+export * from './canonical';
+export * from './keys';
+export * from './did';
+export * from './envelope';
+export * from './cosignature';
+export * from './challenge';
+export * from './webhook';
+export * from './attestation';
+export * from './server-chain';
+export * from './settlement';
+export * from './purpose';
+export * from './utils';
+export * from './types';
+export * from './assets';
+export * from './escrow';