@routedock/nulth-sdk 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RouteDock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,17 @@
+# @routedock/nulth-sdk — Stub / Proof-of-Concept
+
+**Status: STUB — not ready for production.**
+
+This package provides an **insecure mock prover** (`insecureMockProof`) that computes a
+SHA-512 digest as a placeholder. No real zero-knowledge proof is generated.
+
+- The mock prover is only safe for **testnet** development.
+- **`NulthClient` construction throws unless `network` is `'testnet'` and the prover
+  is `'mock'`.** A missing or misspelled network (for example `'pubnet'`) and any
+  other prover backend are rejected, because this package does not currently
+  implement a production prover backend.
+- The `mock` backend is deliberately not a cryptographic proof and must never be
+  used for custody or policy enforcement.
+
+See [Issue #143](https://github.com/winsznx/routedock/issues/143) for context.
+

package/dist/index.cjs

@@ -0,0 +1,357 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  DEFAULT_PROVER: () => DEFAULT_PROVER,
+  NulthClient: () => NulthClient,
+  NulthPolicyError: () => NulthPolicyError,
+  USDC_DECIMALS: () => USDC_DECIMALS,
+  assertAuthEntryMatchesContext: () => assertAuthEntryMatchesContext,
+  authDigestFromEntry: () => authDigestFromEntry,
+  commitAllowlist: () => commitAllowlist,
+  commitDailyCap: () => commitDailyCap,
+  createNulthSigner: () => createNulthSigner,
+  createPolicyState: () => createPolicyState,
+  dayBucket: () => dayBucket,
+  decodeAuthSignature: () => decodeAuthSignature,
+  encodeAuthSignature: () => encodeAuthSignature,
+  hashPayee: () => hashPayee,
+  insecureMockProof: () => insecureMockProof,
+  paymentContextFromManifest: () => paymentContextFromManifest,
+  setNulthPaymentContext: () => setNulthPaymentContext,
+  sha256Hex: () => sha256Hex,
+  usdcToStroops: () => usdcToStroops
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/types.ts
+var NulthPolicyError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "NulthPolicyError";
+    this.code = code;
+  }
+};
+
+// src/proof.ts
+var import_node_crypto = require("crypto");
+var import_stellar_sdk = require("@stellar/stellar-sdk");
+
+// src/usdc.ts
+var USDC_DECIMALS = 7;
+var USDC_SCALE = 10n ** BigInt(USDC_DECIMALS);
+function usdcToStroops(amount) {
+  const match = /^(\d+)(?:\.(\d+))?$/.exec(amount.trim());
+  if (!match) {
+    throw new RangeError(`Invalid USDC amount: "${amount}"`);
+  }
+  const whole = match[1];
+  const frac = match[2] ?? "";
+  if (frac.length > USDC_DECIMALS) {
+    throw new RangeError(
+      `USDC amount "${amount}" exceeds ${USDC_DECIMALS} decimals of precision`
+    );
+  }
+  const fracUnits = BigInt(frac.padEnd(USDC_DECIMALS, "0"));
+  const units = BigInt(whole) * USDC_SCALE + fracUnits;
+  if (units > BigInt(Number.MAX_SAFE_INTEGER)) {
+    throw new RangeError(`USDC amount "${amount}" is too large to represent exactly`);
+  }
+  return units;
+}
+
+// src/proof.ts
+function sha256Hex(data) {
+  const buf = typeof data === "string" ? Buffer.from(data, "utf8") : data;
+  return (0, import_node_crypto.createHash)("sha256").update(buf).digest("hex");
+}
+function commitDailyCap(dailyCapStroops, witnessSecret) {
+  return sha256Hex(`${witnessSecret}:cap:${dailyCapStroops.toString()}`);
+}
+function commitAllowlist(payees, witnessSecret) {
+  const sorted = [...payees].sort().join(",");
+  return sha256Hex(`${witnessSecret}:allowlist:${sorted}`);
+}
+function hashPayee(payee) {
+  return sha256Hex(`payee:${payee}`);
+}
+function dayBucket(ledgerSequence) {
+  return Math.floor(ledgerSequence / 17280);
+}
+function authDigestFromEntry(authEntryBase64) {
+  const entryHash = (0, import_stellar_sdk.hash)(Buffer.from(authEntryBase64, "base64"));
+  return sha256Hex(entryHash);
+}
+function assertAuthEntryMatchesContext(authEntry, from, ctx) {
+  let preimage;
+  try {
+    preimage = import_stellar_sdk.xdr.HashIdPreimage.fromXDR(authEntry, "base64");
+  } catch {
+    throw new NulthPolicyError("auth_entry_mismatch", "authEntry does not decode as a HashIdPreimage");
+  }
+  if (preimage.switch() !== import_stellar_sdk.xdr.EnvelopeType.envelopeTypeSorobanAuthorization()) {
+    throw new NulthPolicyError(
+      "auth_entry_mismatch",
+      "authEntry is not a Soroban authorization preimage"
+    );
+  }
+  const inv = preimage.sorobanAuthorization().invocation();
+  if (inv.subInvocations().length !== 0) {
+    throw new NulthPolicyError("auth_entry_mismatch", "authEntry has unexpected sub-invocations");
+  }
+  if (inv.function().switch() !== import_stellar_sdk.xdr.SorobanAuthorizedFunctionType.sorobanAuthorizedFunctionTypeContractFn()) {
+    throw new NulthPolicyError("auth_entry_mismatch", "authEntry does not invoke a contract function");
+  }
+  const fn = inv.function().contractFn();
+  const contractAddress = import_stellar_sdk.Address.fromScAddress(fn.contractAddress()).toString();
+  if (contractAddress !== ctx.assetContract) {
+    throw new NulthPolicyError(
+      "auth_entry_mismatch",
+      `authEntry contract ${contractAddress} does not match assetContract ${ctx.assetContract}`
+    );
+  }
+  const functionName = fn.functionName().toString();
+  if (functionName !== "transfer") {
+    throw new NulthPolicyError(
+      "auth_entry_mismatch",
+      `authEntry function ${functionName} does not match expected transfer`
+    );
+  }
+  const args = fn.args();
+  if (args.length !== 3) {
+    throw new NulthPolicyError("auth_entry_mismatch", `authEntry transfer has ${args.length} args, expected 3`);
+  }
+  const entryFrom = (0, import_stellar_sdk.scValToNative)(args[0]);
+  if (entryFrom !== from) {
+    throw new NulthPolicyError(
+      "auth_entry_mismatch",
+      `authEntry from ${entryFrom} does not match nulthAccount ${from}`
+    );
+  }
+  const entryTo = (0, import_stellar_sdk.scValToNative)(args[1]);
+  if (entryTo !== ctx.payee) {
+    throw new NulthPolicyError(
+      "auth_entry_mismatch",
+      `authEntry to ${entryTo} does not match paymentContext.payee ${ctx.payee}`
+    );
+  }
+  const entryAmount = (0, import_stellar_sdk.scValToNative)(args[2]);
+  if (entryAmount !== ctx.amountStroops) {
+    throw new NulthPolicyError(
+      "auth_entry_mismatch",
+      `authEntry amount ${entryAmount} does not match paymentContext.amountStroops ${ctx.amountStroops}`
+    );
+  }
+}
+var DEFAULT_PROVER = "mock";
+function insecureMockProof(preimage) {
+  return (0, import_node_crypto.createHash)("sha512").update(`nulth:${preimage}`).digest("base64");
+}
+function encodeAuthSignature(proof) {
+  const payload = {
+    nulth: "zk-v1",
+    proof
+  };
+  return Buffer.from(JSON.stringify(payload), "utf8").toString("base64");
+}
+function decodeAuthSignature(encoded) {
+  const raw = JSON.parse(Buffer.from(encoded, "base64").toString("utf8"));
+  if (typeof raw !== "object" || raw === null || raw.nulth !== "zk-v1") {
+    throw new Error("Invalid Nulth ZK auth signature");
+  }
+  return raw;
+}
+
+// src/NulthClient.ts
+var NulthClient = class {
+  constructor(config) {
+    this.config = config;
+    this.policy = { ...config.policy };
+    this.prover = config.prover ?? DEFAULT_PROVER;
+    if (this.prover !== "mock") {
+      throw new Error(
+        `NulthClient: unknown prover backend ${String(config.prover)}; only 'mock' is implemented`
+      );
+    }
+    if (config.network !== "testnet") {
+      throw new Error(
+        `NulthClient cannot use the insecure mock prover on mainnet; a production prover is required (network must be 'testnet', got ${String(config.network)})`
+      );
+    }
+    console.warn("NulthClient is using the insecure mock prover; proofs are not cryptographically sound");
+  }
+  config;
+  policy;
+  prover;
+  get nulthAccount() {
+    return this.config.nulthAccount;
+  }
+  get allowlistCommitment() {
+    return this.policy.allowlistCommitment;
+  }
+  get capCommitment() {
+    return commitDailyCap(this.policy.dailyCapStroops, this.policy.witnessSecret);
+  }
+  /** Current off-chain daily spend (never published) */
+  get dailySpendStroops() {
+    return this.policy.dailySpendStroops;
+  }
+  /** Prover backend selected for this client */
+  get proverBackend() {
+    return this.prover;
+  }
+  /**
+   * Build a ZK proof that the payment satisfies off-chain policy.
+   * Called by RouteDock before attaching the auth signature to the tx.
+   */
+  buildPaymentAuthProof(context) {
+    this.enforcePolicy(context);
+    const bucket = dayBucket(context.ledgerSequence);
+    if (bucket !== this.policy.dayBucket) {
+      this.policy.dayBucket = bucket;
+      this.policy.dailySpendStroops = 0n;
+    }
+    const authDigest = authDigestFromEntry(context.authEntry);
+    const capCommitment = this.capCommitment;
+    const payeeHash = hashPayee(context.payee);
+    const preimage = [
+      authDigest,
+      this.policy.allowlistCommitment,
+      capCommitment,
+      payeeHash,
+      context.amountStroops.toString(),
+      bucket.toString(),
+      this.config.nulthAccount
+    ].join("|");
+    const proof = {
+      version: 1,
+      proof: insecureMockProof(preimage),
+      publicInputs: {
+        authDigest,
+        allowlistCommitment: this.policy.allowlistCommitment,
+        capCommitment,
+        payeeHash,
+        amountStroops: context.amountStroops.toString(),
+        dayBucket: bucket.toString()
+      }
+    };
+    this.policy.dailySpendStroops += context.amountStroops;
+    return proof;
+  }
+  /** Encode proof for SorobanAddressCredentials.signature */
+  encodeProof(proof) {
+    return encodeAuthSignature(proof);
+  }
+  enforcePolicy(context) {
+    if (this.policy.expiryLedger !== void 0 && context.ledgerSequence > this.policy.expiryLedger) {
+      throw new NulthPolicyError("session_expired", "Nulth session expired");
+    }
+    if (!this.policy.allowedPayees.includes(context.payee)) {
+      throw new NulthPolicyError(
+        "payee_not_allowed",
+        `Payee ${context.payee} not in off-chain allowlist`
+      );
+    }
+    const bucket = dayBucket(context.ledgerSequence);
+    const spend = bucket === this.policy.dayBucket ? this.policy.dailySpendStroops : 0n;
+    const projected = spend + context.amountStroops;
+    if (projected > this.policy.dailyCapStroops) {
+      throw new NulthPolicyError("daily_cap_exceeded", "Nulth daily cap exceeded");
+    }
+  }
+};
+
+// src/signer.ts
+function createNulthSigner(config) {
+  const client = new NulthClient(config);
+  const nulthAccount = config.nulthAccount;
+  return {
+    address: nulthAccount,
+    signAuthEntry: async (authEntry) => {
+      const ctx = config.paymentContext;
+      if (!ctx) {
+        throw new Error(
+          "Nulth paymentContext must be set before signing \u2014 call setNulthPaymentContext()"
+        );
+      }
+      assertAuthEntryMatchesContext(authEntry, nulthAccount, ctx);
+      const proof = client.buildPaymentAuthProof({
+        authEntry,
+        ...ctx
+      });
+      return {
+        signedAuthEntry: encodeAuthSignature(proof),
+        signerAddress: nulthAccount
+      };
+    }
+  };
+}
+function setNulthPaymentContext(config, context) {
+  config.paymentContext = context;
+}
+function paymentContextFromManifest(manifest, mode, ledgerSequence) {
+  const pricing = manifest.pricing[mode];
+  if (!pricing) {
+    throw new Error(`manifest.pricing.${mode} missing`);
+  }
+  return {
+    payee: manifest.payee,
+    amountStroops: usdcToStroops(pricing.amount),
+    assetContract: manifest.asset_contract,
+    ledgerSequence
+  };
+}
+function createPolicyState(input) {
+  const dailyCapStroops = usdcToStroops(input.dailyCapUsdc);
+  const witnessSecret = input.witnessSecret;
+  return {
+    dailyCapStroops,
+    allowlistCommitment: commitAllowlist(input.allowedPayees, witnessSecret),
+    allowedPayees: input.allowedPayees,
+    dailySpendStroops: 0n,
+    dayBucket: dayBucket(input.ledgerSequence ?? 0),
+    witnessSecret,
+    ...input.expiryLedger !== void 0 ? { expiryLedger: input.expiryLedger } : {}
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_PROVER,
+  NulthClient,
+  NulthPolicyError,
+  USDC_DECIMALS,
+  assertAuthEntryMatchesContext,
+  authDigestFromEntry,
+  commitAllowlist,
+  commitDailyCap,
+  createNulthSigner,
+  createPolicyState,
+  dayBucket,
+  decodeAuthSignature,
+  encodeAuthSignature,
+  hashPayee,
+  insecureMockProof,
+  paymentContextFromManifest,
+  setNulthPaymentContext,
+  sha256Hex,
+  usdcToStroops
+});

package/dist/index.d.cts

@@ -0,0 +1,194 @@
+import { SignAuthEntry } from '@stellar/stellar-sdk/contract';
+
+/**
+ * Off-chain policy state for a Nulth ZK account.
+ * Allowlist and daily cap live here — never published on-chain.
+ */
+interface NulthPolicyState {
+    /** Maximum daily spend in stroops (7-decimal USDC) */
+    dailyCapStroops: bigint;
+    /** SHA-256 commitment to sorted allowlisted payee addresses (hex) */
+    allowlistCommitment: string;
+    /** Allowed payee contract/account addresses — kept off-chain */
+    allowedPayees: readonly string[];
+    /** Cumulative spend for the current day bucket */
+    dailySpendStroops: bigint;
+    /** Ledger day bucket: ledger_sequence / 17280 */
+    dayBucket: number;
+    /** Agent witness secret — binds proofs without exposing policy */
+    witnessSecret: string;
+    /** Optional session expiry ledger */
+    expiryLedger?: number;
+}
+/** Inputs for building a payment authorization proof */
+interface PaymentAuthContext {
+    /** Base64 Soroban auth entry preimage from x402 / RouteDock */
+    authEntry: string;
+    /** Destination payee address (G... or C...) */
+    payee: string;
+    /** Transfer amount in stroops */
+    amountStroops: bigint;
+    /** SAC asset contract address */
+    assetContract: string;
+    /** Current ledger sequence (for day bucket + expiry checks) */
+    ledgerSequence: number;
+}
+/** ZK auth proof attached to Soroban __check_auth */
+interface NulthProof {
+    version: 1;
+    /** Groth16-style proof bytes (base64) — verified on-chain, policy stays private */
+    proof: string;
+    /** Public inputs bound into the proof (no raw allowlist or cap values) */
+    publicInputs: {
+        authDigest: string;
+        allowlistCommitment: string;
+        capCommitment: string;
+        payeeHash: string;
+        amountStroops: string;
+        dayBucket: string;
+    };
+}
+/** Encoded signature payload for SorobanAddressCredentials.signature */
+interface NulthAuthSignature {
+    nulth: 'zk-v1';
+    proof: NulthProof;
+}
+interface NulthClientConfig {
+    /** Nulth smart account contract address (C...) — the payer */
+    nulthAccount: string;
+    /**
+     * Network the client will authorize payments on.
+     */
+    network: 'testnet' | 'mainnet';
+    /** Test-only SHA-512 proof stub. */
+    prover?: 'mock';
+    /** Off-chain policy state */
+    policy: NulthPolicyState;
+    /** Optional verifier contract deployed alongside the Nulth account */
+    verifierContract?: string;
+}
+declare class NulthPolicyError extends Error {
+    readonly code: 'payee_not_allowed' | 'daily_cap_exceeded' | 'session_expired' | 'auth_entry_mismatch';
+    constructor(code: NulthPolicyError['code'], message: string);
+}
+
+/**
+ * USDC decimal-to-integer conversion shared by nulth-sdk and @routedock/routedock.
+ *
+ * 1 USDC = 10^7 stroops on Stellar. This is the single canonical converter;
+ * callers in other packages re-export it rather than reimplementing the math.
+ */
+declare const USDC_DECIMALS = 7;
+/**
+ * Parse a decimal USDC string (e.g. "1.00", "0.0001") into exact stroops
+ * (10^-7 USDC) as a bigint, with no floating-point arithmetic.
+ *
+ * Float math drifts: summing many small amounts in `number` USDC
+ * (e.g. 7000 × 0.0001) yields 0.7000000000000006 instead of 0.7, which silently
+ * overruns a spend cap on every boundary crossing. Comparing and accumulating in
+ * this integer domain is exact.
+ *
+ * Throws RangeError on malformed input, negatives, precision finer than
+ * {@link USDC_DECIMALS} decimals, or values too large to represent exactly.
+ */
+declare function usdcToStroops(amount: string): bigint;
+
+/** SHA-256 hex digest */
+declare function sha256Hex(data: Buffer | string): string;
+/** Commitment to the daily cap — cap value never appears on-chain */
+declare function commitDailyCap(dailyCapStroops: bigint, witnessSecret: string): string;
+/** Commitment to sorted allowlist — individual payees never published */
+declare function commitAllowlist(payees: readonly string[], witnessSecret: string): string;
+/** Hash a payee for public inputs without revealing the full allowlist */
+declare function hashPayee(payee: string): string;
+/** Ledger day bucket aligned with agent-vault (17280 ledgers ≈ 24h) */
+declare function dayBucket(ledgerSequence: number): number;
+/** Auth digest bound into the ZK proof (mirrors OZ smart account binding) */
+declare function authDigestFromEntry(authEntryBase64: string): string;
+/**
+ * Verify that the Soroban auth entry actually being signed matches the
+ * off-chain payment context the policy was checked against. Without this,
+ * the policy (allowlist + daily cap) checks `context.payee` /
+ * `context.amountStroops` while a completely different transfer — a
+ * different recipient, amount, or asset — can be the one that actually
+ * gets signed and submitted.
+ *
+ * Throws NulthPolicyError('auth_entry_mismatch', ...) naming the field
+ * that failed to match, or if the entry doesn't even decode as a
+ * `transfer` invocation.
+ */
+declare function assertAuthEntryMatchesContext(authEntry: string, from: string, ctx: Omit<PaymentAuthContext, 'authEntry'>): void;
+type ProverBackend = 'mock';
+declare const DEFAULT_PROVER: ProverBackend;
+/**
+ * Deterministic insecure proof bytes for testnet/dev only.
+ *
+ * @internal
+ */
+declare function insecureMockProof(preimage: string): string;
+/** Encode proof as the Soroban auth signature Val (base64 JSON) */
+declare function encodeAuthSignature(proof: NulthProof): string;
+/** Decode an auth signature produced by {@link encodeAuthSignature} */
+declare function decodeAuthSignature(encoded: string): NulthAuthSignature;
+
+declare class NulthClient {
+    private readonly config;
+    private policy;
+    private readonly prover;
+    constructor(config: NulthClientConfig);
+    get nulthAccount(): string;
+    get allowlistCommitment(): string;
+    get capCommitment(): string;
+    /** Current off-chain daily spend (never published) */
+    get dailySpendStroops(): bigint;
+    /** Prover backend selected for this client */
+    get proverBackend(): ProverBackend;
+    /**
+     * Build a ZK proof that the payment satisfies off-chain policy.
+     * Called by RouteDock before attaching the auth signature to the tx.
+     */
+    buildPaymentAuthProof(context: PaymentAuthContext): NulthProof;
+    /** Encode proof for SorobanAddressCredentials.signature */
+    encodeProof(proof: NulthProof): string;
+    private enforcePolicy;
+}
+
+/** Compatible with @x402/stellar ClientStellarSigner */
+interface NulthStellarSigner {
+    address: string;
+    signAuthEntry: SignAuthEntry;
+}
+interface NulthSignerConfig extends NulthClientConfig {
+    /** Pending payment context set before x402 signs auth entries */
+    paymentContext?: Omit<PaymentAuthContext, 'authEntry'>;
+}
+/**
+ * Create an x402-compatible signer that pays from a Nulth ZK account.
+ * Proofs are built off-chain; allowlist and cap never leave the agent.
+ */
+declare function createNulthSigner(config: NulthSignerConfig): NulthStellarSigner;
+/** Bind the next payment's public context before x402 calls signAuthEntry */
+declare function setNulthPaymentContext(config: NulthSignerConfig, context: Omit<PaymentAuthContext, 'authEntry'>): void;
+/** Helper to prepare payment context from manifest pricing */
+declare function paymentContextFromManifest(manifest: {
+    payee: string;
+    asset_contract: string;
+    pricing: {
+        x402?: {
+            amount: string;
+        };
+        'mpp-charge'?: {
+            amount: string;
+        };
+    };
+}, mode: 'x402' | 'mpp-charge', ledgerSequence: number): Omit<PaymentAuthContext, 'authEntry'>;
+/** Initialize off-chain policy from explicit allowlist + cap (hashed before use) */
+declare function createPolicyState(input: {
+    dailyCapUsdc: string;
+    allowedPayees: readonly string[];
+    witnessSecret: string;
+    expiryLedger?: number;
+    ledgerSequence?: number;
+}): NulthPolicyState;
+
+export { DEFAULT_PROVER, type NulthAuthSignature, NulthClient, type NulthClientConfig, NulthPolicyError, type NulthPolicyState, type NulthProof, type NulthSignerConfig, type NulthStellarSigner, type PaymentAuthContext, type ProverBackend, USDC_DECIMALS, assertAuthEntryMatchesContext, authDigestFromEntry, commitAllowlist, commitDailyCap, createNulthSigner, createPolicyState, dayBucket, decodeAuthSignature, encodeAuthSignature, hashPayee, insecureMockProof, paymentContextFromManifest, setNulthPaymentContext, sha256Hex, usdcToStroops };

package/dist/index.d.ts

@@ -0,0 +1,194 @@
+import { SignAuthEntry } from '@stellar/stellar-sdk/contract';
+
+/**
+ * Off-chain policy state for a Nulth ZK account.
+ * Allowlist and daily cap live here — never published on-chain.
+ */
+interface NulthPolicyState {
+    /** Maximum daily spend in stroops (7-decimal USDC) */
+    dailyCapStroops: bigint;
+    /** SHA-256 commitment to sorted allowlisted payee addresses (hex) */
+    allowlistCommitment: string;
+    /** Allowed payee contract/account addresses — kept off-chain */
+    allowedPayees: readonly string[];
+    /** Cumulative spend for the current day bucket */
+    dailySpendStroops: bigint;
+    /** Ledger day bucket: ledger_sequence / 17280 */
+    dayBucket: number;
+    /** Agent witness secret — binds proofs without exposing policy */
+    witnessSecret: string;
+    /** Optional session expiry ledger */
+    expiryLedger?: number;
+}
+/** Inputs for building a payment authorization proof */
+interface PaymentAuthContext {
+    /** Base64 Soroban auth entry preimage from x402 / RouteDock */
+    authEntry: string;
+    /** Destination payee address (G... or C...) */
+    payee: string;
+    /** Transfer amount in stroops */
+    amountStroops: bigint;
+    /** SAC asset contract address */
+    assetContract: string;
+    /** Current ledger sequence (for day bucket + expiry checks) */
+    ledgerSequence: number;
+}
+/** ZK auth proof attached to Soroban __check_auth */
+interface NulthProof {
+    version: 1;
+    /** Groth16-style proof bytes (base64) — verified on-chain, policy stays private */
+    proof: string;
+    /** Public inputs bound into the proof (no raw allowlist or cap values) */
+    publicInputs: {
+        authDigest: string;
+        allowlistCommitment: string;
+        capCommitment: string;
+        payeeHash: string;
+        amountStroops: string;
+        dayBucket: string;
+    };
+}
+/** Encoded signature payload for SorobanAddressCredentials.signature */
+interface NulthAuthSignature {
+    nulth: 'zk-v1';
+    proof: NulthProof;
+}
+interface NulthClientConfig {
+    /** Nulth smart account contract address (C...) — the payer */
+    nulthAccount: string;
+    /**
+     * Network the client will authorize payments on.
+     */
+    network: 'testnet' | 'mainnet';
+    /** Test-only SHA-512 proof stub. */
+    prover?: 'mock';
+    /** Off-chain policy state */
+    policy: NulthPolicyState;
+    /** Optional verifier contract deployed alongside the Nulth account */
+    verifierContract?: string;
+}
+declare class NulthPolicyError extends Error {
+    readonly code: 'payee_not_allowed' | 'daily_cap_exceeded' | 'session_expired' | 'auth_entry_mismatch';
+    constructor(code: NulthPolicyError['code'], message: string);
+}
+
+/**
+ * USDC decimal-to-integer conversion shared by nulth-sdk and @routedock/routedock.
+ *
+ * 1 USDC = 10^7 stroops on Stellar. This is the single canonical converter;
+ * callers in other packages re-export it rather than reimplementing the math.
+ */
+declare const USDC_DECIMALS = 7;
+/**
+ * Parse a decimal USDC string (e.g. "1.00", "0.0001") into exact stroops
+ * (10^-7 USDC) as a bigint, with no floating-point arithmetic.
+ *
+ * Float math drifts: summing many small amounts in `number` USDC
+ * (e.g. 7000 × 0.0001) yields 0.7000000000000006 instead of 0.7, which silently
+ * overruns a spend cap on every boundary crossing. Comparing and accumulating in
+ * this integer domain is exact.
+ *
+ * Throws RangeError on malformed input, negatives, precision finer than
+ * {@link USDC_DECIMALS} decimals, or values too large to represent exactly.
+ */
+declare function usdcToStroops(amount: string): bigint;
+
+/** SHA-256 hex digest */
+declare function sha256Hex(data: Buffer | string): string;
+/** Commitment to the daily cap — cap value never appears on-chain */
+declare function commitDailyCap(dailyCapStroops: bigint, witnessSecret: string): string;
+/** Commitment to sorted allowlist — individual payees never published */
+declare function commitAllowlist(payees: readonly string[], witnessSecret: string): string;
+/** Hash a payee for public inputs without revealing the full allowlist */
+declare function hashPayee(payee: string): string;
+/** Ledger day bucket aligned with agent-vault (17280 ledgers ≈ 24h) */
+declare function dayBucket(ledgerSequence: number): number;
+/** Auth digest bound into the ZK proof (mirrors OZ smart account binding) */
+declare function authDigestFromEntry(authEntryBase64: string): string;
+/**
+ * Verify that the Soroban auth entry actually being signed matches the
+ * off-chain payment context the policy was checked against. Without this,
+ * the policy (allowlist + daily cap) checks `context.payee` /
+ * `context.amountStroops` while a completely different transfer — a
+ * different recipient, amount, or asset — can be the one that actually
+ * gets signed and submitted.
+ *
+ * Throws NulthPolicyError('auth_entry_mismatch', ...) naming the field
+ * that failed to match, or if the entry doesn't even decode as a
+ * `transfer` invocation.
+ */
+declare function assertAuthEntryMatchesContext(authEntry: string, from: string, ctx: Omit<PaymentAuthContext, 'authEntry'>): void;
+type ProverBackend = 'mock';
+declare const DEFAULT_PROVER: ProverBackend;
+/**
+ * Deterministic insecure proof bytes for testnet/dev only.
+ *
+ * @internal
+ */
+declare function insecureMockProof(preimage: string): string;
+/** Encode proof as the Soroban auth signature Val (base64 JSON) */
+declare function encodeAuthSignature(proof: NulthProof): string;
+/** Decode an auth signature produced by {@link encodeAuthSignature} */
+declare function decodeAuthSignature(encoded: string): NulthAuthSignature;
+
+declare class NulthClient {
+    private readonly config;
+    private policy;
+    private readonly prover;
+    constructor(config: NulthClientConfig);
+    get nulthAccount(): string;
+    get allowlistCommitment(): string;
+    get capCommitment(): string;
+    /** Current off-chain daily spend (never published) */
+    get dailySpendStroops(): bigint;
+    /** Prover backend selected for this client */
+    get proverBackend(): ProverBackend;
+    /**
+     * Build a ZK proof that the payment satisfies off-chain policy.
+     * Called by RouteDock before attaching the auth signature to the tx.
+     */
+    buildPaymentAuthProof(context: PaymentAuthContext): NulthProof;
+    /** Encode proof for SorobanAddressCredentials.signature */
+    encodeProof(proof: NulthProof): string;
+    private enforcePolicy;
+}
+
+/** Compatible with @x402/stellar ClientStellarSigner */
+interface NulthStellarSigner {
+    address: string;
+    signAuthEntry: SignAuthEntry;
+}
+interface NulthSignerConfig extends NulthClientConfig {
+    /** Pending payment context set before x402 signs auth entries */
+    paymentContext?: Omit<PaymentAuthContext, 'authEntry'>;
+}
+/**
+ * Create an x402-compatible signer that pays from a Nulth ZK account.
+ * Proofs are built off-chain; allowlist and cap never leave the agent.
+ */
+declare function createNulthSigner(config: NulthSignerConfig): NulthStellarSigner;
+/** Bind the next payment's public context before x402 calls signAuthEntry */
+declare function setNulthPaymentContext(config: NulthSignerConfig, context: Omit<PaymentAuthContext, 'authEntry'>): void;
+/** Helper to prepare payment context from manifest pricing */
+declare function paymentContextFromManifest(manifest: {
+    payee: string;
+    asset_contract: string;
+    pricing: {
+        x402?: {
+            amount: string;
+        };
+        'mpp-charge'?: {
+            amount: string;
+        };
+    };
+}, mode: 'x402' | 'mpp-charge', ledgerSequence: number): Omit<PaymentAuthContext, 'authEntry'>;
+/** Initialize off-chain policy from explicit allowlist + cap (hashed before use) */
+declare function createPolicyState(input: {
+    dailyCapUsdc: string;
+    allowedPayees: readonly string[];
+    witnessSecret: string;
+    expiryLedger?: number;
+    ledgerSequence?: number;
+}): NulthPolicyState;
+
+export { DEFAULT_PROVER, type NulthAuthSignature, NulthClient, type NulthClientConfig, NulthPolicyError, type NulthPolicyState, type NulthProof, type NulthSignerConfig, type NulthStellarSigner, type PaymentAuthContext, type ProverBackend, USDC_DECIMALS, assertAuthEntryMatchesContext, authDigestFromEntry, commitAllowlist, commitDailyCap, createNulthSigner, createPolicyState, dayBucket, decodeAuthSignature, encodeAuthSignature, hashPayee, insecureMockProof, paymentContextFromManifest, setNulthPaymentContext, sha256Hex, usdcToStroops };

package/dist/index.js

@@ -0,0 +1,312 @@
+// src/types.ts
+var NulthPolicyError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "NulthPolicyError";
+    this.code = code;
+  }
+};
+
+// src/proof.ts
+import { createHash } from "crypto";
+import { Address, hash, scValToNative, xdr } from "@stellar/stellar-sdk";
+
+// src/usdc.ts
+var USDC_DECIMALS = 7;
+var USDC_SCALE = 10n ** BigInt(USDC_DECIMALS);
+function usdcToStroops(amount) {
+  const match = /^(\d+)(?:\.(\d+))?$/.exec(amount.trim());
+  if (!match) {
+    throw new RangeError(`Invalid USDC amount: "${amount}"`);
+  }
+  const whole = match[1];
+  const frac = match[2] ?? "";
+  if (frac.length > USDC_DECIMALS) {
+    throw new RangeError(
+      `USDC amount "${amount}" exceeds ${USDC_DECIMALS} decimals of precision`
+    );
+  }
+  const fracUnits = BigInt(frac.padEnd(USDC_DECIMALS, "0"));
+  const units = BigInt(whole) * USDC_SCALE + fracUnits;
+  if (units > BigInt(Number.MAX_SAFE_INTEGER)) {
+    throw new RangeError(`USDC amount "${amount}" is too large to represent exactly`);
+  }
+  return units;
+}
+
+// src/proof.ts
+function sha256Hex(data) {
+  const buf = typeof data === "string" ? Buffer.from(data, "utf8") : data;
+  return createHash("sha256").update(buf).digest("hex");
+}
+function commitDailyCap(dailyCapStroops, witnessSecret) {
+  return sha256Hex(`${witnessSecret}:cap:${dailyCapStroops.toString()}`);
+}
+function commitAllowlist(payees, witnessSecret) {
+  const sorted = [...payees].sort().join(",");
+  return sha256Hex(`${witnessSecret}:allowlist:${sorted}`);
+}
+function hashPayee(payee) {
+  return sha256Hex(`payee:${payee}`);
+}
+function dayBucket(ledgerSequence) {
+  return Math.floor(ledgerSequence / 17280);
+}
+function authDigestFromEntry(authEntryBase64) {
+  const entryHash = hash(Buffer.from(authEntryBase64, "base64"));
+  return sha256Hex(entryHash);
+}
+function assertAuthEntryMatchesContext(authEntry, from, ctx) {
+  let preimage;
+  try {
+    preimage = xdr.HashIdPreimage.fromXDR(authEntry, "base64");
+  } catch {
+    throw new NulthPolicyError("auth_entry_mismatch", "authEntry does not decode as a HashIdPreimage");
+  }
+  if (preimage.switch() !== xdr.EnvelopeType.envelopeTypeSorobanAuthorization()) {
+    throw new NulthPolicyError(
+      "auth_entry_mismatch",
+      "authEntry is not a Soroban authorization preimage"
+    );
+  }
+  const inv = preimage.sorobanAuthorization().invocation();
+  if (inv.subInvocations().length !== 0) {
+    throw new NulthPolicyError("auth_entry_mismatch", "authEntry has unexpected sub-invocations");
+  }
+  if (inv.function().switch() !== xdr.SorobanAuthorizedFunctionType.sorobanAuthorizedFunctionTypeContractFn()) {
+    throw new NulthPolicyError("auth_entry_mismatch", "authEntry does not invoke a contract function");
+  }
+  const fn = inv.function().contractFn();
+  const contractAddress = Address.fromScAddress(fn.contractAddress()).toString();
+  if (contractAddress !== ctx.assetContract) {
+    throw new NulthPolicyError(
+      "auth_entry_mismatch",
+      `authEntry contract ${contractAddress} does not match assetContract ${ctx.assetContract}`
+    );
+  }
+  const functionName = fn.functionName().toString();
+  if (functionName !== "transfer") {
+    throw new NulthPolicyError(
+      "auth_entry_mismatch",
+      `authEntry function ${functionName} does not match expected transfer`
+    );
+  }
+  const args = fn.args();
+  if (args.length !== 3) {
+    throw new NulthPolicyError("auth_entry_mismatch", `authEntry transfer has ${args.length} args, expected 3`);
+  }
+  const entryFrom = scValToNative(args[0]);
+  if (entryFrom !== from) {
+    throw new NulthPolicyError(
+      "auth_entry_mismatch",
+      `authEntry from ${entryFrom} does not match nulthAccount ${from}`
+    );
+  }
+  const entryTo = scValToNative(args[1]);
+  if (entryTo !== ctx.payee) {
+    throw new NulthPolicyError(
+      "auth_entry_mismatch",
+      `authEntry to ${entryTo} does not match paymentContext.payee ${ctx.payee}`
+    );
+  }
+  const entryAmount = scValToNative(args[2]);
+  if (entryAmount !== ctx.amountStroops) {
+    throw new NulthPolicyError(
+      "auth_entry_mismatch",
+      `authEntry amount ${entryAmount} does not match paymentContext.amountStroops ${ctx.amountStroops}`
+    );
+  }
+}
+var DEFAULT_PROVER = "mock";
+function insecureMockProof(preimage) {
+  return createHash("sha512").update(`nulth:${preimage}`).digest("base64");
+}
+function encodeAuthSignature(proof) {
+  const payload = {
+    nulth: "zk-v1",
+    proof
+  };
+  return Buffer.from(JSON.stringify(payload), "utf8").toString("base64");
+}
+function decodeAuthSignature(encoded) {
+  const raw = JSON.parse(Buffer.from(encoded, "base64").toString("utf8"));
+  if (typeof raw !== "object" || raw === null || raw.nulth !== "zk-v1") {
+    throw new Error("Invalid Nulth ZK auth signature");
+  }
+  return raw;
+}
+
+// src/NulthClient.ts
+var NulthClient = class {
+  constructor(config) {
+    this.config = config;
+    this.policy = { ...config.policy };
+    this.prover = config.prover ?? DEFAULT_PROVER;
+    if (this.prover !== "mock") {
+      throw new Error(
+        `NulthClient: unknown prover backend ${String(config.prover)}; only 'mock' is implemented`
+      );
+    }
+    if (config.network !== "testnet") {
+      throw new Error(
+        `NulthClient cannot use the insecure mock prover on mainnet; a production prover is required (network must be 'testnet', got ${String(config.network)})`
+      );
+    }
+    console.warn("NulthClient is using the insecure mock prover; proofs are not cryptographically sound");
+  }
+  config;
+  policy;
+  prover;
+  get nulthAccount() {
+    return this.config.nulthAccount;
+  }
+  get allowlistCommitment() {
+    return this.policy.allowlistCommitment;
+  }
+  get capCommitment() {
+    return commitDailyCap(this.policy.dailyCapStroops, this.policy.witnessSecret);
+  }
+  /** Current off-chain daily spend (never published) */
+  get dailySpendStroops() {
+    return this.policy.dailySpendStroops;
+  }
+  /** Prover backend selected for this client */
+  get proverBackend() {
+    return this.prover;
+  }
+  /**
+   * Build a ZK proof that the payment satisfies off-chain policy.
+   * Called by RouteDock before attaching the auth signature to the tx.
+   */
+  buildPaymentAuthProof(context) {
+    this.enforcePolicy(context);
+    const bucket = dayBucket(context.ledgerSequence);
+    if (bucket !== this.policy.dayBucket) {
+      this.policy.dayBucket = bucket;
+      this.policy.dailySpendStroops = 0n;
+    }
+    const authDigest = authDigestFromEntry(context.authEntry);
+    const capCommitment = this.capCommitment;
+    const payeeHash = hashPayee(context.payee);
+    const preimage = [
+      authDigest,
+      this.policy.allowlistCommitment,
+      capCommitment,
+      payeeHash,
+      context.amountStroops.toString(),
+      bucket.toString(),
+      this.config.nulthAccount
+    ].join("|");
+    const proof = {
+      version: 1,
+      proof: insecureMockProof(preimage),
+      publicInputs: {
+        authDigest,
+        allowlistCommitment: this.policy.allowlistCommitment,
+        capCommitment,
+        payeeHash,
+        amountStroops: context.amountStroops.toString(),
+        dayBucket: bucket.toString()
+      }
+    };
+    this.policy.dailySpendStroops += context.amountStroops;
+    return proof;
+  }
+  /** Encode proof for SorobanAddressCredentials.signature */
+  encodeProof(proof) {
+    return encodeAuthSignature(proof);
+  }
+  enforcePolicy(context) {
+    if (this.policy.expiryLedger !== void 0 && context.ledgerSequence > this.policy.expiryLedger) {
+      throw new NulthPolicyError("session_expired", "Nulth session expired");
+    }
+    if (!this.policy.allowedPayees.includes(context.payee)) {
+      throw new NulthPolicyError(
+        "payee_not_allowed",
+        `Payee ${context.payee} not in off-chain allowlist`
+      );
+    }
+    const bucket = dayBucket(context.ledgerSequence);
+    const spend = bucket === this.policy.dayBucket ? this.policy.dailySpendStroops : 0n;
+    const projected = spend + context.amountStroops;
+    if (projected > this.policy.dailyCapStroops) {
+      throw new NulthPolicyError("daily_cap_exceeded", "Nulth daily cap exceeded");
+    }
+  }
+};
+
+// src/signer.ts
+function createNulthSigner(config) {
+  const client = new NulthClient(config);
+  const nulthAccount = config.nulthAccount;
+  return {
+    address: nulthAccount,
+    signAuthEntry: async (authEntry) => {
+      const ctx = config.paymentContext;
+      if (!ctx) {
+        throw new Error(
+          "Nulth paymentContext must be set before signing \u2014 call setNulthPaymentContext()"
+        );
+      }
+      assertAuthEntryMatchesContext(authEntry, nulthAccount, ctx);
+      const proof = client.buildPaymentAuthProof({
+        authEntry,
+        ...ctx
+      });
+      return {
+        signedAuthEntry: encodeAuthSignature(proof),
+        signerAddress: nulthAccount
+      };
+    }
+  };
+}
+function setNulthPaymentContext(config, context) {
+  config.paymentContext = context;
+}
+function paymentContextFromManifest(manifest, mode, ledgerSequence) {
+  const pricing = manifest.pricing[mode];
+  if (!pricing) {
+    throw new Error(`manifest.pricing.${mode} missing`);
+  }
+  return {
+    payee: manifest.payee,
+    amountStroops: usdcToStroops(pricing.amount),
+    assetContract: manifest.asset_contract,
+    ledgerSequence
+  };
+}
+function createPolicyState(input) {
+  const dailyCapStroops = usdcToStroops(input.dailyCapUsdc);
+  const witnessSecret = input.witnessSecret;
+  return {
+    dailyCapStroops,
+    allowlistCommitment: commitAllowlist(input.allowedPayees, witnessSecret),
+    allowedPayees: input.allowedPayees,
+    dailySpendStroops: 0n,
+    dayBucket: dayBucket(input.ledgerSequence ?? 0),
+    witnessSecret,
+    ...input.expiryLedger !== void 0 ? { expiryLedger: input.expiryLedger } : {}
+  };
+}
+export {
+  DEFAULT_PROVER,
+  NulthClient,
+  NulthPolicyError,
+  USDC_DECIMALS,
+  assertAuthEntryMatchesContext,
+  authDigestFromEntry,
+  commitAllowlist,
+  commitDailyCap,
+  createNulthSigner,
+  createPolicyState,
+  dayBucket,
+  decodeAuthSignature,
+  encodeAuthSignature,
+  hashPayee,
+  insecureMockProof,
+  paymentContextFromManifest,
+  setNulthPaymentContext,
+  sha256Hex,
+  usdcToStroops
+};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@routedock/nulth-sdk",
+  "version": "0.2.0",
+  "description": "Off-chain ZK proof builder for Nulth smart accounts on Stellar",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "dependencies": {
+    "@stellar/stellar-sdk": "^14.6.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsup": "^8.0.0",
+    "tsx": "^4.22.3",
+    "typescript": "^5.4.5"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "tsx --test src/__tests__/nulth.test.ts"
+  }
+}