@routedock/nulth-sdk 0.2.2 → 0.3.0

package/README.md

@@ -2,16 +2,135 @@
 
 **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.
+This package provides an **insecure mock prover** (`insecureMockProof`). It produces a
+SHA-512 digest as a placeholder; no real zero-knowledge proof is generated. Use it
+only for **testnet development**, never for custody or production policy enforcement.
+`NulthClient` rejects every network except `testnet` and every prover except `mock`.
+See [Issue #143](https://github.com/winsznx/routedock/issues/143) for production prover work.
+
+## Requirements
+
+Node.js **22 or newer**, matching the supported runtime of the RouteDock packages.
+TypeScript examples use ES2022 or later for native `bigint` support.
+
+## Install
+
+```bash
+npm install @routedock/nulth-sdk
+```
+
+## Example: initialize a testnet client
+
+Set `NULTH_ACCOUNT` to your testnet smart-account contract address (`C...`) and
+`TESTNET_PAYEE` to an allowed testnet recipient (`G...` or `C...`). This example
+initializes local policy state and prints commitments; it does not submit a payment.
+Persist the witness secret securely if you need to recreate the same commitments.
+
+```ts
+import { randomBytes } from 'node:crypto'
+import {
+  createPolicyState,
+  NulthClient,
+  stroopsToUsdc,
+} from '@routedock/nulth-sdk'
+
+const nulthAccount = process.env.NULTH_ACCOUNT
+const payee = process.env.TESTNET_PAYEE
+if (!nulthAccount || !payee) {
+  throw new Error('Set NULTH_ACCOUNT and TESTNET_PAYEE to testnet addresses')
+}
+
+const policy = createPolicyState({
+  dailyCapUsdc: '1.00',
+  allowedPayees: [payee],
+  witnessSecret: randomBytes(32).toString('hex'),
+})
+const client = new NulthClient({
+  nulthAccount,
+  network: 'testnet',
+  prover: 'mock',
+  policy,
+})
+
+console.log(client.allowlistCommitment, client.capCommitment)
+console.log(stroopsToUsdc(client.dailySpendStroops)) // '0'
+```
+
+Before using the signing adapter, supply the payment's real ledger sequence, asset,
+payee, and amount through `setNulthPaymentContext`. `createNulthSigner` checks the
+actual Soroban authorization preimage against that context. A missing context or
+mismatched transfer is rejected. These client-side checks do not make the mock proof secure.
+
+## Exports
+
+| Export | Purpose |
+| --- | --- |
+| `NulthClient` | Testnet-only client with policy checks, mock proof construction, encoding, and spend/commitment getters. |
+| `createPolicyState` | Initialize off-chain policy from a decimal USDC cap, payees, witness secret, and optional ledger/expiry. |
+| `createNulthSigner` | Create an x402-compatible signer for a Nulth account using the mock client. |
+| `setNulthPaymentContext` | Set the next payment context on the configuration used by the signer. |
+| `paymentContextFromManifest` | Extract asset, payee, amount, and ledger context from manifest pricing. |
+| `assertAuthEntryMatchesContext` | Reject an authorization preimage whose transfer does not match the expected payer, payee, asset, or amount. |
+| `usdcToStroops`, `stroopsToUsdc`, `USDC_DECIMALS` | Convert decimal USDC strings and integer units using seven decimal places. |
+| `commitAllowlist`, `commitDailyCap` | Compute salted SHA-256 commitments to policy values. |
+| `dayBucket` | Convert a ledger sequence to its 17,280-ledger day bucket. |
+| `hashPayee`, `authDigestFromEntry`, `sha256Hex` | Hash payees, authorization preimages, and byte/string inputs. |
+| `encodeAuthSignature`, `decodeAuthSignature` | Encode or decode the mock signature envelope as base64 JSON; decoding is not proof verification. |
+| `insecureMockProof`, `DEFAULT_PROVER` | Produce deterministic SHA-512 placeholder bytes and identify the only supported backend (`mock`). |
+| `NulthPolicyError` | Typed policy rejection with a `code` such as `daily_cap_exceeded` or `auth_entry_mismatch`. |
+| `NulthPolicyState`, `NulthClientConfig`, `PaymentAuthContext` | Types for policy state, client configuration, and payment authorization inputs. |
+| `NulthSignerConfig`, `NulthStellarSigner` | Types for mutable signer configuration and its signing interface. |
+| `NulthProof`, `NulthAuthSignature`, `ProverBackend` | Types for the mock proof, signature envelope, and prover selection. |
+
+## What the mock prover does and does not prove
+
+`NulthClient` checks the local allowlist, daily cap, and optional session expiry,
+then hashes public inputs into deterministic placeholder bytes. Building a proof
+updates the client's in-memory daily spend; it is not evidence of on-chain settlement
+and does not provide durable accounting across process restarts.
+
+The digest is **not a zero-knowledge proof** and proves neither knowledge of a secret
+witness nor satisfaction of the policy to an on-chain verifier. Anyone can reproduce
+it from the public preimage. Commitments alone do not provide a production security
+boundary, and the public inputs expose payment amounts, day buckets, and hashes.
+A real prover/verifier integration is still required before this package can protect funds.
+
+For contributors, `pnpm --filter @routedock/nulth-sdk check:readme` typechecks every
+TypeScript example against the built package exports. It also runs during `pnpm verify`.
+## Diagnostics and configuration errors
+
+Diagnostics are silent by default. Pass a `logger(level, message, fields?)` in
+`NulthClientConfig` (also accepted by `createNulthSigner`) to receive the mock-prover
+warning. The sink is compatible with RouteDock's `RouteDockLogger`; the RouteDock
+SDK adapter retains its console-backed default and accepts the same override.
+
+Invalid networks and prover backends throw `NulthConfigError`, with code
+`unsupported_network` or `unsupported_prover`. The RouteDock adapter maps these
+to `RouteDockManifestError`; policy failures remain `NulthPolicyError`.
+
+## Paying through x402 with a Nulth account
+
+`src/scheme.ts` carries the pieces the SDK needs to let a Nulth ZK account sign an
+x402 payment:
+
+- `NULTH_SIGNER_MARKER` — a `Symbol.for` key set on every signer from
+  `createNulthSigner()`. `@routedock/routedock` uses it to pick the Nulth payment
+  scheme instead of the plain ed25519 one, so no caller has to opt in.
+- `nulthProofScVal` / `decodeNulthProofScVal` — the `zk-v1` envelope, a
+  `scvVec` of one map with `nulth`, `version`, `proof`, `auth_digest`,
+  `allowlist_commitment`, `cap_commitment`, `payee_hash`, `amount_stroops` and
+  `day_bucket`. The proof and its public inputs go into
+  `SorobanAddressCredentials.signature`; the allowlist and the daily cap never
+  leave the agent.
+- `nulthAuthorizeEntry` — the `authorizeEntry` replacement. stellar-sdk's
+  default writes `scvVec([nativeToScVal({public_key, signature})])`, and for a
+  `C...` contract account that path throws
+  `invalid version byte. expected 48, got 16` (see
+  [Issue #356](https://github.com/winsznx/routedock/issues/356)), so a Nulth
+  payment can never be signed with it.
+
+**What still is not here:** the contract side. There is no Nulth account contract
+in this repository that implements `__check_auth` against these public inputs, and
+no Groth16 verifier is deployed, so a proof produced by the mock prover is not
+settled on-chain. Testnet builds are for developing the client path only.
 

package/dist/index.cjs

@@ -21,7 +21,10 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   DEFAULT_PROVER: () => DEFAULT_PROVER,
+  NULTH_SIGNATURE_VERSION: () => NULTH_SIGNATURE_VERSION,
+  NULTH_SIGNER_MARKER: () => NULTH_SIGNER_MARKER,
   NulthClient: () => NulthClient,
+  NulthConfigError: () => NulthConfigError,
   NulthPolicyError: () => NulthPolicyError,
   USDC_DECIMALS: () => USDC_DECIMALS,
   assertAuthEntryMatchesContext: () => assertAuthEntryMatchesContext,
@@ -32,9 +35,13 @@ __export(index_exports, {
   createPolicyState: () => createPolicyState,
   dayBucket: () => dayBucket,
   decodeAuthSignature: () => decodeAuthSignature,
+  decodeNulthProofScVal: () => decodeNulthProofScVal,
   encodeAuthSignature: () => encodeAuthSignature,
   hashPayee: () => hashPayee,
   insecureMockProof: () => insecureMockProof,
+  isNulthStellarSigner: () => isNulthStellarSigner,
+  nulthAuthorizeEntry: () => nulthAuthorizeEntry,
+  nulthProofScVal: () => nulthProofScVal,
   paymentContextFromManifest: () => paymentContextFromManifest,
   setNulthPaymentContext: () => setNulthPaymentContext,
   sha256Hex: () => sha256Hex,
@@ -44,6 +51,14 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/types.ts
+var NulthConfigError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "NulthConfigError";
+    this.code = code;
+  }
+};
 var NulthPolicyError = class extends Error {
   code;
   constructor(code, message) {
@@ -54,9 +69,51 @@ var NulthPolicyError = class extends Error {
 };
 
 // src/proof.ts
-var import_node_crypto = require("crypto");
 var import_stellar_sdk = require("@stellar/stellar-sdk");
 
+// src/encoding.ts
+var import_sha2 = require("@noble/hashes/sha2.js");
+var encoder = new TextEncoder();
+var decoder = new TextDecoder();
+function utf8ToBytes(text) {
+  return encoder.encode(text);
+}
+function bytesToUtf8(bytes) {
+  return decoder.decode(bytes);
+}
+function bytesToBase64(bytes) {
+  const chunk = 32768;
+  let binary = "";
+  for (let i = 0; i < bytes.length; i += chunk) {
+    binary += String.fromCharCode(...bytes.subarray(i, i + chunk));
+  }
+  return btoa(binary);
+}
+function base64ToBytes(b64) {
+  const end = b64.indexOf("=");
+  let clean = (end === -1 ? b64 : b64.slice(0, end)).replace(/-/g, "+").replace(/_/g, "/").replace(/[^A-Za-z0-9+/]/g, "");
+  if (clean.length % 4 === 1) clean = clean.slice(0, -1);
+  const binary = atob(clean);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}
+function bytesToHex(bytes) {
+  let out = "";
+  for (let i = 0; i < bytes.length; i++) {
+    out += bytes[i].toString(16).padStart(2, "0");
+  }
+  return out;
+}
+function sha256Bytes(data) {
+  return (0, import_sha2.sha256)(typeof data === "string" ? utf8ToBytes(data) : data);
+}
+function sha512Bytes(data) {
+  return (0, import_sha2.sha512)(typeof data === "string" ? utf8ToBytes(data) : data);
+}
+
 // src/usdc.ts
 var USDC_DECIMALS = 7;
 var USDC_SCALE = 10n ** BigInt(USDC_DECIMALS);
@@ -92,8 +149,7 @@ function stroopsToUsdc(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");
+  return bytesToHex(sha256Bytes(data));
 }
 function commitDailyCap(dailyCapStroops, witnessSecret) {
   return sha256Hex(`${witnessSecret}:cap:${dailyCapStroops.toString()}`);
@@ -109,7 +165,7 @@ function dayBucket(ledgerSequence) {
   return Math.floor(ledgerSequence / 17280);
 }
 function authDigestFromEntry(authEntryBase64) {
-  const entryHash = (0, import_stellar_sdk.hash)(Buffer.from(authEntryBase64, "base64"));
+  const entryHash = (0, import_stellar_sdk.hash)(base64ToBytes(authEntryBase64));
   return sha256Hex(entryHash);
 }
 function assertAuthEntryMatchesContext(authEntry, from, ctx) {
@@ -175,17 +231,17 @@ function assertAuthEntryMatchesContext(authEntry, from, ctx) {
 }
 var DEFAULT_PROVER = "mock";
 function insecureMockProof(preimage) {
-  return (0, import_node_crypto.createHash)("sha512").update(`nulth:${preimage}`).digest("base64");
+  return bytesToBase64(sha512Bytes(`nulth:${preimage}`));
 }
 function encodeAuthSignature(proof) {
   const payload = {
     nulth: "zk-v1",
     proof
   };
-  return Buffer.from(JSON.stringify(payload), "utf8").toString("base64");
+  return bytesToBase64(utf8ToBytes(JSON.stringify(payload)));
 }
 function decodeAuthSignature(encoded) {
-  const raw = JSON.parse(Buffer.from(encoded, "base64").toString("utf8"));
+  const raw = JSON.parse(bytesToUtf8(base64ToBytes(encoded)));
   if (typeof raw !== "object" || raw === null || raw.nulth !== "zk-v1") {
     throw new Error("Invalid Nulth ZK auth signature");
   }
@@ -199,16 +255,21 @@ var NulthClient = class {
     this.policy = { ...config.policy };
     this.prover = config.prover ?? DEFAULT_PROVER;
     if (this.prover !== "mock") {
-      throw new Error(
+      throw new NulthConfigError(
+        "unsupported_prover",
         `NulthClient: unknown prover backend ${String(config.prover)}; only 'mock' is implemented`
       );
     }
     if (config.network !== "testnet") {
-      throw new Error(
+      throw new NulthConfigError(
+        "unsupported_network",
         `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.logger?.(
+      "warn",
+      "NulthClient is using the insecure mock prover; proofs are not cryptographically sound"
+    );
   }
   config;
   policy;
@@ -297,12 +358,144 @@ var NulthClient = class {
   }
 };
 
+// src/scheme.ts
+var import_stellar_sdk2 = require("@stellar/stellar-sdk");
+var NULTH_SIGNATURE_VERSION = "zk-v1";
+var NULTH_SIGNER_MARKER = /* @__PURE__ */ Symbol.for("routedock.nulth.signer");
+function isNulthStellarSigner(signer) {
+  return signer[NULTH_SIGNER_MARKER] === NULTH_SIGNATURE_VERSION;
+}
+var SCVAL_TYPES = {
+  nulth: ["symbol", "string"],
+  version: ["symbol", "u32"],
+  proof: ["symbol", "bytes"],
+  auth_digest: ["symbol", "string"],
+  allowlist_commitment: ["symbol", "string"],
+  cap_commitment: ["symbol", "string"],
+  payee_hash: ["symbol", "string"],
+  amount_stroops: ["symbol", "i128"],
+  day_bucket: ["symbol", "u64"]
+};
+function nulthProofScVal(signature) {
+  if (signature.nulth !== NULTH_SIGNATURE_VERSION) {
+    throw new RangeError(`unsupported Nulth signature format ${String(signature.nulth)}`);
+  }
+  const { proof } = signature;
+  const inputs = proof.publicInputs;
+  return import_stellar_sdk2.xdr.ScVal.scvVec([
+    (0, import_stellar_sdk2.nativeToScVal)(
+      {
+        nulth: signature.nulth,
+        version: proof.version,
+        proof: base64ToBytes(proof.proof),
+        auth_digest: inputs.authDigest,
+        allowlist_commitment: inputs.allowlistCommitment,
+        cap_commitment: inputs.capCommitment,
+        payee_hash: inputs.payeeHash,
+        amount_stroops: BigInt(inputs.amountStroops),
+        day_bucket: BigInt(inputs.dayBucket)
+      },
+      { type: SCVAL_TYPES }
+    )
+  ]);
+}
+function requiredString(value, field) {
+  if (typeof value !== "string") {
+    throw new TypeError(`Nulth signature field ${field} is not a string`);
+  }
+  return value;
+}
+function requiredBytes(value, field) {
+  if (!(value instanceof Uint8Array)) {
+    throw new TypeError(`Nulth signature field ${field} is not bytes`);
+  }
+  return bytesToBase64(value);
+}
+function requiredNumber(value, field) {
+  const num = Number(value);
+  if (!Number.isInteger(num)) {
+    throw new TypeError(`Nulth signature field ${field} is not an integer`);
+  }
+  return num;
+}
+function requiredDecimal(value, field) {
+  if (typeof value === "string") return value;
+  if (typeof value === "bigint" || typeof value === "number") return value.toString();
+  throw new TypeError(`Nulth signature field ${field} is not a decimal value`);
+}
+function decodeNulthProofScVal(signature) {
+  if (signature.switch() !== import_stellar_sdk2.xdr.ScValType.scvVec()) {
+    throw new TypeError("Nulth signature is not a vec");
+  }
+  const entries = signature.vec();
+  if (!entries || entries.length !== 1) {
+    throw new TypeError(`Nulth signature vec must hold exactly one map, got ${entries?.length ?? 0}`);
+  }
+  const fields = (0, import_stellar_sdk2.scValToNative)(entries[0]);
+  const nulth = requiredString(fields.nulth, "nulth");
+  if (nulth !== NULTH_SIGNATURE_VERSION) {
+    throw new TypeError(`unsupported Nulth signature format ${nulth}`);
+  }
+  const proof = {
+    version: requiredNumber(fields.version, "version"),
+    proof: requiredBytes(fields.proof, "proof"),
+    publicInputs: {
+      authDigest: requiredString(fields.auth_digest, "auth_digest"),
+      allowlistCommitment: requiredString(fields.allowlist_commitment, "allowlist_commitment"),
+      capCommitment: requiredString(fields.cap_commitment, "cap_commitment"),
+      payeeHash: requiredString(fields.payee_hash, "payee_hash"),
+      amountStroops: requiredDecimal(fields.amount_stroops, "amount_stroops"),
+      dayBucket: requiredDecimal(fields.day_bucket, "day_bucket")
+    }
+  };
+  return { nulth: NULTH_SIGNATURE_VERSION, proof };
+}
+async function nulthAuthorizeEntry(entry, signer, validUntilLedgerSeq, networkPassphrase) {
+  if (entry.credentials().switch() !== import_stellar_sdk2.xdr.SorobanCredentialsType.sorobanCredentialsAddress()) {
+    return entry;
+  }
+  if (typeof signer !== "function") {
+    throw new TypeError(
+      "nulthAuthorizeEntry needs a callback that returns the zk-v1 proof envelope; a Keypair can only produce an ed25519 signature"
+    );
+  }
+  if (!networkPassphrase) {
+    throw new TypeError("nulthAuthorizeEntry needs the network passphrase to build the preimage");
+  }
+  const clone = import_stellar_sdk2.xdr.SorobanAuthorizationEntry.fromXDR(entry.toXDR());
+  const credentials = clone.credentials().address();
+  const address = import_stellar_sdk2.Address.fromScAddress(credentials.address()).toString();
+  if (!address.startsWith("C")) {
+    throw new TypeError(
+      `nulthAuthorizeEntry signs Nulth contract accounts (C...) only, got ${address}`
+    );
+  }
+  credentials.signatureExpirationLedger(validUntilLedgerSeq);
+  const preimage = import_stellar_sdk2.xdr.HashIdPreimage.envelopeTypeSorobanAuthorization(
+    new import_stellar_sdk2.xdr.HashIdPreimageSorobanAuthorization({
+      networkId: (0, import_stellar_sdk2.hash)(utf8ToBytes(networkPassphrase)),
+      nonce: credentials.nonce(),
+      invocation: clone.rootInvocation(),
+      signatureExpirationLedger: credentials.signatureExpirationLedger()
+    })
+  );
+  const signed = await signer(preimage);
+  credentials.signature(nulthProofScVal(decodeAuthSignature(envelopeBase64(signed))));
+  return clone;
+}
+function envelopeBase64(signed) {
+  if (signed instanceof Uint8Array) return bytesToBase64(signed);
+  if (signed instanceof ArrayBuffer) return bytesToBase64(new Uint8Array(signed));
+  throw new TypeError("Nulth signing callback must return the zk-v1 envelope as bytes");
+}
+
 // src/signer.ts
 function createNulthSigner(config) {
   const client = new NulthClient(config);
   const nulthAccount = config.nulthAccount;
   return {
     address: nulthAccount,
+    [NULTH_SIGNER_MARKER]: NULTH_SIGNATURE_VERSION,
     signAuthEntry: async (authEntry) => {
       const ctx = config.paymentContext;
       if (!ctx) {
@@ -353,7 +546,10 @@ function createPolicyState(input) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   DEFAULT_PROVER,
+  NULTH_SIGNATURE_VERSION,
+  NULTH_SIGNER_MARKER,
   NulthClient,
+  NulthConfigError,
   NulthPolicyError,
   USDC_DECIMALS,
   assertAuthEntryMatchesContext,
@@ -364,9 +560,13 @@ function createPolicyState(input) {
   createPolicyState,
   dayBucket,
   decodeAuthSignature,
+  decodeNulthProofScVal,
   encodeAuthSignature,
   hashPayee,
   insecureMockProof,
+  isNulthStellarSigner,
+  nulthAuthorizeEntry,
+  nulthProofScVal,
   paymentContextFromManifest,
   setNulthPaymentContext,
   sha256Hex,

package/dist/index.d.cts

@@ -1,4 +1,5 @@
 import { SignAuthEntry } from '@stellar/stellar-sdk/contract';
+import { xdr, SigningCallback, Keypair } from '@stellar/stellar-sdk';
 
 /**
  * Off-chain policy state for a Nulth ZK account.
@@ -53,6 +54,8 @@ interface NulthAuthSignature {
     nulth: 'zk-v1';
     proof: NulthProof;
 }
+/** Consumer-supplied diagnostic sink, compatible with RouteDockLogger. */
+type NulthLogger = (level: 'debug' | 'info' | 'warn' | 'error', message: string, fields?: Record<string, unknown>) => void;
 interface NulthClientConfig {
     /** Nulth smart account contract address (C...) — the payer */
     nulthAccount: string;
@@ -66,6 +69,13 @@ interface NulthClientConfig {
     policy: NulthPolicyState;
     /** Optional verifier contract deployed alongside the Nulth account */
     verifierContract?: string;
+    /** Log sink for the mock-prover warning. Defaults to no-op (silent). */
+    logger?: NulthLogger;
+}
+/** Invalid network or prover configuration, distinct from policy failures. */
+declare class NulthConfigError extends Error {
+    readonly code: 'unsupported_prover' | 'unsupported_network';
+    constructor(code: NulthConfigError['code'], message: string);
 }
 declare class NulthPolicyError extends Error {
     readonly code: 'payee_not_allowed' | 'daily_cap_exceeded' | 'session_expired' | 'auth_entry_mismatch';
@@ -106,7 +116,7 @@ declare function usdcToStroops(amount: string): bigint;
 declare function stroopsToUsdc(units: bigint): string;
 
 /** SHA-256 hex digest */
-declare function sha256Hex(data: Buffer | string): string;
+declare function sha256Hex(data: Uint8Array | 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 */
@@ -165,10 +175,60 @@ declare class NulthClient {
     private enforcePolicy;
 }
 
+/**
+ * A Nulth proof travels in the Soroban auth entry's signature field instead of
+ * an ed25519 signature, so stellar-sdk's default `authorizeEntry` (which decodes
+ * the credential address as an ed25519 key and therefore throws
+ * `invalid version byte. expected 48, got 16` for a `C...` payer) cannot be used.
+ */
+/** Tag identifying the `zk-v1` signature layout, matching {@link NulthAuthSignature.nulth}. */
+declare const NULTH_SIGNATURE_VERSION = "zk-v1";
+/**
+ * Global-registry symbol set on signers produced by {@link createNulthSigner}, so
+ * an x402 client can pick the Nulth scheme without importing the signer factory.
+ * Registered globally because `@routedock/routedock` ships its own inlined copy of
+ * the signer (see #575); two copies of the same symbol must still compare equal.
+ */
+declare const NULTH_SIGNER_MARKER: unique symbol;
+/** Anything carrying the marker is payer-side Nulth: contract account + proof signature. */
+interface NulthSignerMarker {
+    readonly [NULTH_SIGNER_MARKER]: typeof NULTH_SIGNATURE_VERSION;
+}
+declare function isNulthStellarSigner(signer: object): boolean;
+/**
+ * Encode a Nulth proof as the `SorobanAddressCredentials.signature` a Nulth
+ * account contract's `__check_auth` reads: `vec[map]`, the same shape Stellar uses
+ * for account signatures (`vec[{public_key, signature}]`), with the proof fields
+ * flattened into the map so the contract can map each one to a public input
+ * without parsing JSON.
+ */
+declare function nulthProofScVal(signature: NulthAuthSignature): xdr.ScVal;
+/**
+ * Decode a signature ScVal written by {@link nulthProofScVal}. A Nulth account
+ * contract reads the same map; this is the client/provider-side mirror of that
+ * read, used to prove a signed entry round-trips.
+ */
+declare function decodeNulthProofScVal(signature: xdr.ScVal): NulthAuthSignature;
+/**
+ * Build the signature the Nulth account authorises: sign the authorization
+ * preimage through the Nulth signer, which runs the off-chain policy checks and
+ * returns the `zk-v1` envelope, then write the proof into the credentials.
+ *
+ * Mirrors stellar-base's `authorizeEntry` in the parts that matter — the preimage
+ * is built identically, so the digest the proof binds is the one the network
+ * recomputes — and replaces the ed25519 verification and `{public_key, signature}`
+ * vec with {@link nulthProofScVal}. The parameter list matches
+ * `typeof authorizeEntry` deliberately, so it can be handed to
+ * `AssembledTransaction.signAuthEntries` as its `authorizeEntry` override.
+ */
+declare function nulthAuthorizeEntry(entry: xdr.SorobanAuthorizationEntry, signer: SigningCallback | Keypair, validUntilLedgerSeq: number, networkPassphrase?: string): Promise<xdr.SorobanAuthorizationEntry>;
+
 /** Compatible with @x402/stellar ClientStellarSigner */
 interface NulthStellarSigner {
     address: string;
     signAuthEntry: SignAuthEntry;
+    /** Marks this signer as Nulth so the x402 client selects the proof scheme. */
+    readonly [NULTH_SIGNER_MARKER]: typeof NULTH_SIGNATURE_VERSION;
 }
 interface NulthSignerConfig extends NulthClientConfig {
     /** Pending payment context set before x402 signs auth entries */
@@ -205,4 +265,4 @@ declare function createPolicyState(input: {
     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, stroopsToUsdc, usdcToStroops };
+export { DEFAULT_PROVER, NULTH_SIGNATURE_VERSION, NULTH_SIGNER_MARKER, type NulthAuthSignature, NulthClient, type NulthClientConfig, NulthConfigError, type NulthLogger, NulthPolicyError, type NulthPolicyState, type NulthProof, type NulthSignerConfig, type NulthSignerMarker, type NulthStellarSigner, type PaymentAuthContext, type ProverBackend, USDC_DECIMALS, assertAuthEntryMatchesContext, authDigestFromEntry, commitAllowlist, commitDailyCap, createNulthSigner, createPolicyState, dayBucket, decodeAuthSignature, decodeNulthProofScVal, encodeAuthSignature, hashPayee, insecureMockProof, isNulthStellarSigner, nulthAuthorizeEntry, nulthProofScVal, paymentContextFromManifest, setNulthPaymentContext, sha256Hex, stroopsToUsdc, usdcToStroops };

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { SignAuthEntry } from '@stellar/stellar-sdk/contract';
+import { xdr, SigningCallback, Keypair } from '@stellar/stellar-sdk';
 
 /**
  * Off-chain policy state for a Nulth ZK account.
@@ -53,6 +54,8 @@ interface NulthAuthSignature {
     nulth: 'zk-v1';
     proof: NulthProof;
 }
+/** Consumer-supplied diagnostic sink, compatible with RouteDockLogger. */
+type NulthLogger = (level: 'debug' | 'info' | 'warn' | 'error', message: string, fields?: Record<string, unknown>) => void;
 interface NulthClientConfig {
     /** Nulth smart account contract address (C...) — the payer */
     nulthAccount: string;
@@ -66,6 +69,13 @@ interface NulthClientConfig {
     policy: NulthPolicyState;
     /** Optional verifier contract deployed alongside the Nulth account */
     verifierContract?: string;
+    /** Log sink for the mock-prover warning. Defaults to no-op (silent). */
+    logger?: NulthLogger;
+}
+/** Invalid network or prover configuration, distinct from policy failures. */
+declare class NulthConfigError extends Error {
+    readonly code: 'unsupported_prover' | 'unsupported_network';
+    constructor(code: NulthConfigError['code'], message: string);
 }
 declare class NulthPolicyError extends Error {
     readonly code: 'payee_not_allowed' | 'daily_cap_exceeded' | 'session_expired' | 'auth_entry_mismatch';
@@ -106,7 +116,7 @@ declare function usdcToStroops(amount: string): bigint;
 declare function stroopsToUsdc(units: bigint): string;
 
 /** SHA-256 hex digest */
-declare function sha256Hex(data: Buffer | string): string;
+declare function sha256Hex(data: Uint8Array | 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 */
@@ -165,10 +175,60 @@ declare class NulthClient {
     private enforcePolicy;
 }
 
+/**
+ * A Nulth proof travels in the Soroban auth entry's signature field instead of
+ * an ed25519 signature, so stellar-sdk's default `authorizeEntry` (which decodes
+ * the credential address as an ed25519 key and therefore throws
+ * `invalid version byte. expected 48, got 16` for a `C...` payer) cannot be used.
+ */
+/** Tag identifying the `zk-v1` signature layout, matching {@link NulthAuthSignature.nulth}. */
+declare const NULTH_SIGNATURE_VERSION = "zk-v1";
+/**
+ * Global-registry symbol set on signers produced by {@link createNulthSigner}, so
+ * an x402 client can pick the Nulth scheme without importing the signer factory.
+ * Registered globally because `@routedock/routedock` ships its own inlined copy of
+ * the signer (see #575); two copies of the same symbol must still compare equal.
+ */
+declare const NULTH_SIGNER_MARKER: unique symbol;
+/** Anything carrying the marker is payer-side Nulth: contract account + proof signature. */
+interface NulthSignerMarker {
+    readonly [NULTH_SIGNER_MARKER]: typeof NULTH_SIGNATURE_VERSION;
+}
+declare function isNulthStellarSigner(signer: object): boolean;
+/**
+ * Encode a Nulth proof as the `SorobanAddressCredentials.signature` a Nulth
+ * account contract's `__check_auth` reads: `vec[map]`, the same shape Stellar uses
+ * for account signatures (`vec[{public_key, signature}]`), with the proof fields
+ * flattened into the map so the contract can map each one to a public input
+ * without parsing JSON.
+ */
+declare function nulthProofScVal(signature: NulthAuthSignature): xdr.ScVal;
+/**
+ * Decode a signature ScVal written by {@link nulthProofScVal}. A Nulth account
+ * contract reads the same map; this is the client/provider-side mirror of that
+ * read, used to prove a signed entry round-trips.
+ */
+declare function decodeNulthProofScVal(signature: xdr.ScVal): NulthAuthSignature;
+/**
+ * Build the signature the Nulth account authorises: sign the authorization
+ * preimage through the Nulth signer, which runs the off-chain policy checks and
+ * returns the `zk-v1` envelope, then write the proof into the credentials.
+ *
+ * Mirrors stellar-base's `authorizeEntry` in the parts that matter — the preimage
+ * is built identically, so the digest the proof binds is the one the network
+ * recomputes — and replaces the ed25519 verification and `{public_key, signature}`
+ * vec with {@link nulthProofScVal}. The parameter list matches
+ * `typeof authorizeEntry` deliberately, so it can be handed to
+ * `AssembledTransaction.signAuthEntries` as its `authorizeEntry` override.
+ */
+declare function nulthAuthorizeEntry(entry: xdr.SorobanAuthorizationEntry, signer: SigningCallback | Keypair, validUntilLedgerSeq: number, networkPassphrase?: string): Promise<xdr.SorobanAuthorizationEntry>;
+
 /** Compatible with @x402/stellar ClientStellarSigner */
 interface NulthStellarSigner {
     address: string;
     signAuthEntry: SignAuthEntry;
+    /** Marks this signer as Nulth so the x402 client selects the proof scheme. */
+    readonly [NULTH_SIGNER_MARKER]: typeof NULTH_SIGNATURE_VERSION;
 }
 interface NulthSignerConfig extends NulthClientConfig {
     /** Pending payment context set before x402 signs auth entries */
@@ -205,4 +265,4 @@ declare function createPolicyState(input: {
     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, stroopsToUsdc, usdcToStroops };
+export { DEFAULT_PROVER, NULTH_SIGNATURE_VERSION, NULTH_SIGNER_MARKER, type NulthAuthSignature, NulthClient, type NulthClientConfig, NulthConfigError, type NulthLogger, NulthPolicyError, type NulthPolicyState, type NulthProof, type NulthSignerConfig, type NulthSignerMarker, type NulthStellarSigner, type PaymentAuthContext, type ProverBackend, USDC_DECIMALS, assertAuthEntryMatchesContext, authDigestFromEntry, commitAllowlist, commitDailyCap, createNulthSigner, createPolicyState, dayBucket, decodeAuthSignature, decodeNulthProofScVal, encodeAuthSignature, hashPayee, insecureMockProof, isNulthStellarSigner, nulthAuthorizeEntry, nulthProofScVal, paymentContextFromManifest, setNulthPaymentContext, sha256Hex, stroopsToUsdc, usdcToStroops };

package/dist/index.js

@@ -1,4 +1,12 @@
 // src/types.ts
+var NulthConfigError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "NulthConfigError";
+    this.code = code;
+  }
+};
 var NulthPolicyError = class extends Error {
   code;
   constructor(code, message) {
@@ -9,9 +17,51 @@ var NulthPolicyError = class extends Error {
 };
 
 // src/proof.ts
-import { createHash } from "crypto";
 import { Address, hash, scValToNative, xdr } from "@stellar/stellar-sdk";
 
+// src/encoding.ts
+import { sha256 as nobleSha256, sha512 as nobleSha512 } from "@noble/hashes/sha2.js";
+var encoder = new TextEncoder();
+var decoder = new TextDecoder();
+function utf8ToBytes(text) {
+  return encoder.encode(text);
+}
+function bytesToUtf8(bytes) {
+  return decoder.decode(bytes);
+}
+function bytesToBase64(bytes) {
+  const chunk = 32768;
+  let binary = "";
+  for (let i = 0; i < bytes.length; i += chunk) {
+    binary += String.fromCharCode(...bytes.subarray(i, i + chunk));
+  }
+  return btoa(binary);
+}
+function base64ToBytes(b64) {
+  const end = b64.indexOf("=");
+  let clean = (end === -1 ? b64 : b64.slice(0, end)).replace(/-/g, "+").replace(/_/g, "/").replace(/[^A-Za-z0-9+/]/g, "");
+  if (clean.length % 4 === 1) clean = clean.slice(0, -1);
+  const binary = atob(clean);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}
+function bytesToHex(bytes) {
+  let out = "";
+  for (let i = 0; i < bytes.length; i++) {
+    out += bytes[i].toString(16).padStart(2, "0");
+  }
+  return out;
+}
+function sha256Bytes(data) {
+  return nobleSha256(typeof data === "string" ? utf8ToBytes(data) : data);
+}
+function sha512Bytes(data) {
+  return nobleSha512(typeof data === "string" ? utf8ToBytes(data) : data);
+}
+
 // src/usdc.ts
 var USDC_DECIMALS = 7;
 var USDC_SCALE = 10n ** BigInt(USDC_DECIMALS);
@@ -47,8 +97,7 @@ function stroopsToUsdc(units) {
 
 // src/proof.ts
 function sha256Hex(data) {
-  const buf = typeof data === "string" ? Buffer.from(data, "utf8") : data;
-  return createHash("sha256").update(buf).digest("hex");
+  return bytesToHex(sha256Bytes(data));
 }
 function commitDailyCap(dailyCapStroops, witnessSecret) {
   return sha256Hex(`${witnessSecret}:cap:${dailyCapStroops.toString()}`);
@@ -64,7 +113,7 @@ function dayBucket(ledgerSequence) {
   return Math.floor(ledgerSequence / 17280);
 }
 function authDigestFromEntry(authEntryBase64) {
-  const entryHash = hash(Buffer.from(authEntryBase64, "base64"));
+  const entryHash = hash(base64ToBytes(authEntryBase64));
   return sha256Hex(entryHash);
 }
 function assertAuthEntryMatchesContext(authEntry, from, ctx) {
@@ -130,17 +179,17 @@ function assertAuthEntryMatchesContext(authEntry, from, ctx) {
 }
 var DEFAULT_PROVER = "mock";
 function insecureMockProof(preimage) {
-  return createHash("sha512").update(`nulth:${preimage}`).digest("base64");
+  return bytesToBase64(sha512Bytes(`nulth:${preimage}`));
 }
 function encodeAuthSignature(proof) {
   const payload = {
     nulth: "zk-v1",
     proof
   };
-  return Buffer.from(JSON.stringify(payload), "utf8").toString("base64");
+  return bytesToBase64(utf8ToBytes(JSON.stringify(payload)));
 }
 function decodeAuthSignature(encoded) {
-  const raw = JSON.parse(Buffer.from(encoded, "base64").toString("utf8"));
+  const raw = JSON.parse(bytesToUtf8(base64ToBytes(encoded)));
   if (typeof raw !== "object" || raw === null || raw.nulth !== "zk-v1") {
     throw new Error("Invalid Nulth ZK auth signature");
   }
@@ -154,16 +203,21 @@ var NulthClient = class {
     this.policy = { ...config.policy };
     this.prover = config.prover ?? DEFAULT_PROVER;
     if (this.prover !== "mock") {
-      throw new Error(
+      throw new NulthConfigError(
+        "unsupported_prover",
         `NulthClient: unknown prover backend ${String(config.prover)}; only 'mock' is implemented`
       );
     }
     if (config.network !== "testnet") {
-      throw new Error(
+      throw new NulthConfigError(
+        "unsupported_network",
         `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.logger?.(
+      "warn",
+      "NulthClient is using the insecure mock prover; proofs are not cryptographically sound"
+    );
   }
   config;
   policy;
@@ -252,12 +306,144 @@ var NulthClient = class {
   }
 };
 
+// src/scheme.ts
+import { Address as Address2, hash as hash2, nativeToScVal, scValToNative as scValToNative2, xdr as xdr2 } from "@stellar/stellar-sdk";
+var NULTH_SIGNATURE_VERSION = "zk-v1";
+var NULTH_SIGNER_MARKER = /* @__PURE__ */ Symbol.for("routedock.nulth.signer");
+function isNulthStellarSigner(signer) {
+  return signer[NULTH_SIGNER_MARKER] === NULTH_SIGNATURE_VERSION;
+}
+var SCVAL_TYPES = {
+  nulth: ["symbol", "string"],
+  version: ["symbol", "u32"],
+  proof: ["symbol", "bytes"],
+  auth_digest: ["symbol", "string"],
+  allowlist_commitment: ["symbol", "string"],
+  cap_commitment: ["symbol", "string"],
+  payee_hash: ["symbol", "string"],
+  amount_stroops: ["symbol", "i128"],
+  day_bucket: ["symbol", "u64"]
+};
+function nulthProofScVal(signature) {
+  if (signature.nulth !== NULTH_SIGNATURE_VERSION) {
+    throw new RangeError(`unsupported Nulth signature format ${String(signature.nulth)}`);
+  }
+  const { proof } = signature;
+  const inputs = proof.publicInputs;
+  return xdr2.ScVal.scvVec([
+    nativeToScVal(
+      {
+        nulth: signature.nulth,
+        version: proof.version,
+        proof: base64ToBytes(proof.proof),
+        auth_digest: inputs.authDigest,
+        allowlist_commitment: inputs.allowlistCommitment,
+        cap_commitment: inputs.capCommitment,
+        payee_hash: inputs.payeeHash,
+        amount_stroops: BigInt(inputs.amountStroops),
+        day_bucket: BigInt(inputs.dayBucket)
+      },
+      { type: SCVAL_TYPES }
+    )
+  ]);
+}
+function requiredString(value, field) {
+  if (typeof value !== "string") {
+    throw new TypeError(`Nulth signature field ${field} is not a string`);
+  }
+  return value;
+}
+function requiredBytes(value, field) {
+  if (!(value instanceof Uint8Array)) {
+    throw new TypeError(`Nulth signature field ${field} is not bytes`);
+  }
+  return bytesToBase64(value);
+}
+function requiredNumber(value, field) {
+  const num = Number(value);
+  if (!Number.isInteger(num)) {
+    throw new TypeError(`Nulth signature field ${field} is not an integer`);
+  }
+  return num;
+}
+function requiredDecimal(value, field) {
+  if (typeof value === "string") return value;
+  if (typeof value === "bigint" || typeof value === "number") return value.toString();
+  throw new TypeError(`Nulth signature field ${field} is not a decimal value`);
+}
+function decodeNulthProofScVal(signature) {
+  if (signature.switch() !== xdr2.ScValType.scvVec()) {
+    throw new TypeError("Nulth signature is not a vec");
+  }
+  const entries = signature.vec();
+  if (!entries || entries.length !== 1) {
+    throw new TypeError(`Nulth signature vec must hold exactly one map, got ${entries?.length ?? 0}`);
+  }
+  const fields = scValToNative2(entries[0]);
+  const nulth = requiredString(fields.nulth, "nulth");
+  if (nulth !== NULTH_SIGNATURE_VERSION) {
+    throw new TypeError(`unsupported Nulth signature format ${nulth}`);
+  }
+  const proof = {
+    version: requiredNumber(fields.version, "version"),
+    proof: requiredBytes(fields.proof, "proof"),
+    publicInputs: {
+      authDigest: requiredString(fields.auth_digest, "auth_digest"),
+      allowlistCommitment: requiredString(fields.allowlist_commitment, "allowlist_commitment"),
+      capCommitment: requiredString(fields.cap_commitment, "cap_commitment"),
+      payeeHash: requiredString(fields.payee_hash, "payee_hash"),
+      amountStroops: requiredDecimal(fields.amount_stroops, "amount_stroops"),
+      dayBucket: requiredDecimal(fields.day_bucket, "day_bucket")
+    }
+  };
+  return { nulth: NULTH_SIGNATURE_VERSION, proof };
+}
+async function nulthAuthorizeEntry(entry, signer, validUntilLedgerSeq, networkPassphrase) {
+  if (entry.credentials().switch() !== xdr2.SorobanCredentialsType.sorobanCredentialsAddress()) {
+    return entry;
+  }
+  if (typeof signer !== "function") {
+    throw new TypeError(
+      "nulthAuthorizeEntry needs a callback that returns the zk-v1 proof envelope; a Keypair can only produce an ed25519 signature"
+    );
+  }
+  if (!networkPassphrase) {
+    throw new TypeError("nulthAuthorizeEntry needs the network passphrase to build the preimage");
+  }
+  const clone = xdr2.SorobanAuthorizationEntry.fromXDR(entry.toXDR());
+  const credentials = clone.credentials().address();
+  const address = Address2.fromScAddress(credentials.address()).toString();
+  if (!address.startsWith("C")) {
+    throw new TypeError(
+      `nulthAuthorizeEntry signs Nulth contract accounts (C...) only, got ${address}`
+    );
+  }
+  credentials.signatureExpirationLedger(validUntilLedgerSeq);
+  const preimage = xdr2.HashIdPreimage.envelopeTypeSorobanAuthorization(
+    new xdr2.HashIdPreimageSorobanAuthorization({
+      networkId: hash2(utf8ToBytes(networkPassphrase)),
+      nonce: credentials.nonce(),
+      invocation: clone.rootInvocation(),
+      signatureExpirationLedger: credentials.signatureExpirationLedger()
+    })
+  );
+  const signed = await signer(preimage);
+  credentials.signature(nulthProofScVal(decodeAuthSignature(envelopeBase64(signed))));
+  return clone;
+}
+function envelopeBase64(signed) {
+  if (signed instanceof Uint8Array) return bytesToBase64(signed);
+  if (signed instanceof ArrayBuffer) return bytesToBase64(new Uint8Array(signed));
+  throw new TypeError("Nulth signing callback must return the zk-v1 envelope as bytes");
+}
+
 // src/signer.ts
 function createNulthSigner(config) {
   const client = new NulthClient(config);
   const nulthAccount = config.nulthAccount;
   return {
     address: nulthAccount,
+    [NULTH_SIGNER_MARKER]: NULTH_SIGNATURE_VERSION,
     signAuthEntry: async (authEntry) => {
       const ctx = config.paymentContext;
       if (!ctx) {
@@ -307,7 +493,10 @@ function createPolicyState(input) {
 }
 export {
   DEFAULT_PROVER,
+  NULTH_SIGNATURE_VERSION,
+  NULTH_SIGNER_MARKER,
   NulthClient,
+  NulthConfigError,
   NulthPolicyError,
   USDC_DECIMALS,
   assertAuthEntryMatchesContext,
@@ -318,9 +507,13 @@ export {
   createPolicyState,
   dayBucket,
   decodeAuthSignature,
+  decodeNulthProofScVal,
   encodeAuthSignature,
   hashPayee,
   insecureMockProof,
+  isNulthStellarSigner,
+  nulthAuthorizeEntry,
+  nulthProofScVal,
   paymentContextFromManifest,
   setNulthPaymentContext,
   sha256Hex,

package/package.json

@@ -1,8 +1,20 @@
 {
   "name": "@routedock/nulth-sdk",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Off-chain ZK proof builder for Nulth smart accounts on Stellar",
   "license": "MIT",
+  "homepage": "https://github.com/winsznx/routedock/tree/main/packages/nulth-sdk#readme",
+  "bugs": {
+    "url": "https://github.com/winsznx/routedock/issues"
+  },
+  "publishConfig": {
+    "provenance": true
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/winsznx/routedock.git",
+    "directory": "packages/nulth-sdk"
+  },
   "type": "module",
   "main": "dist/index.cjs",
   "module": "dist/index.js",
@@ -24,6 +36,7 @@
     }
   },
   "dependencies": {
+    "@noble/hashes": "^1.8.0",
     "@stellar/stellar-sdk": "^14.6.1"
   },
   "devDependencies": {
@@ -32,9 +45,23 @@
     "tsx": "^4.22.3",
     "typescript": "^5.4.5"
   },
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "stellar",
+    "soroban",
+    "usdc",
+    "x402",
+    "mpp",
+    "payments",
+    "ai-agents",
+    "zk"
+  ],
   "scripts": {
     "build": "tsup",
     "typecheck": "tsc --noEmit",
-    "test": "tsx --test src/__tests__/nulth.test.ts"
+    "test": "tsx --test src/__tests__/*.test.ts",
+    "check:readme": "node ../../scripts/check-nulth-readme.mjs"
   }
 }