@x1id/resolve 0.15.1 → 0.17.0

package/dist/voucher.d.ts

@@ -18,11 +18,12 @@
  *
  * # Lifecycle (mirror of lib.rs)
  *
- * - `create_voucher(name, handleType, recipient, expiresAt)` escrows the mint
- *   price (a snapshot of the live price) into `["voucher", name]` and reserves
- *   the voucher slot. `recipient` bound ⇒ the claim registers the handle to
- *   that wallet no matter who submits; `null` ⇒ open-code (the claimer owns
- *   it). An optional integrator referrer (the same trailing accounts as
+ * - `create_voucher(name, handleType, recipient, expiresAt, claimSecretHash)`
+ *   escrows the mint price (a snapshot of the live price) into
+ *   `["voucher", name]` and reserves the voucher slot. `recipient` bound ⇒ the
+ *   claim registers the handle to that wallet no matter who submits; `null` ⇒
+ *   open-code (the claimer owns it) and `claimSecretHash` (= `sha256(secret)`)
+ *   is REQUIRED (M72) — the claimer must present the matching `secret`. An optional integrator referrer (the same trailing accounts as
  *   `register`, from `integrator.ts`) is snapshotted so the claim can split
  *   the escrow. `expiresAt` must be strictly in the future.
  * - `claim_voucher(name)` registers the handle, drawing the fee from the
@@ -52,6 +53,20 @@ export declare const HandleType: {
     readonly Agent: 3;
 };
 export type HandleTypeValue = (typeof HandleType)[keyof typeof HandleType];
+/**
+ * 32 bytes of fresh CSPRNG output — an OPEN gift voucher's claim secret (M72).
+ * Keep it OUT of the path/query (it belongs in the gift link's URL *fragment*,
+ * which is never sent to a server); its `sha256` ({@link giftSecretHash}) is
+ * what goes on chain as `claim_secret_hash`.
+ */
+export declare function giftSecret(): Uint8Array;
+/**
+ * `sha256(secret)` — the 32-byte `claim_secret_hash` an OPEN voucher stores at
+ * create and the program recomputes from the claimer's `claim_secret` (M72;
+ * mismatch ⇒ `BadClaimSecret`, 6105). WebCrypto, so async — mirrors
+ * commitReveal's `commitmentHash`.
+ */
+export declare function giftSecretHash(secret: Uint8Array): Promise<Uint8Array>;
 /** Decoded `PrepaidVoucher` account. */
 export interface PrepaidVoucher {
     /** Who funded it and gets the refund (base58). */
@@ -69,12 +84,19 @@ export interface PrepaidVoucher {
     readonly integratorRateBps: number;
     readonly expiresAt: bigint;
     readonly createdAt: bigint;
+    /** The `sha256(claim_secret)` an OPEN voucher stores (M72), or null for a
+     *  bound voucher (and for legacy pre-M72 vouchers). An open voucher's claim
+     *  must present a `claim_secret` whose sha256 equals this. */
+    readonly claimSecretHash: Uint8Array | null;
     readonly bump: number;
 }
 /**
  * Decode a `PrepaidVoucher` account's raw data, or null if not one. Parsed
- * sequentially (Borsh): the two `Option<Pubkey>` fields are 1 byte when
- * absent, 33 when present, so fixed offsets after them would be wrong.
+ * sequentially (Borsh): the two `Option<Pubkey>` fields AND the M72
+ * `Option<[u8;32]> claim_secret_hash` are 1 byte when absent, 33 when present,
+ * so fixed offsets after them would be wrong. `claim_secret_hash` sits AFTER
+ * `created_at` and BEFORE `bump` (+33 bytes at its Some size — the Anchor
+ * INIT_SPACE voucher grew 167 → 200 B).
  */
 export declare function decodePrepaidVoucher(data: Uint8Array): PrepaidVoucher | null;
 export interface CreateVoucherParams {
@@ -94,10 +116,17 @@ export interface CreateVoucherParams {
     readonly recipient?: AddressLike | null;
     /** Unix seconds; must be strictly in the future. */
     readonly expiresAt: bigint | number;
+    /** `sha256(claim_secret)` (32 bytes) for an OPEN gift (M72) — REQUIRED when
+     *  `recipient` is null (else the program fails `OpenVoucherNeedsSecret`,
+     *  6104). Ignored/stored None for a bound recipient; pass null (the default)
+     *  for a bound gift. Compute it with {@link giftSecretHash}. */
+    readonly claimSecretHash?: Uint8Array | null;
     /** Optional integrator pair from `integratorAccountsForCreateVoucher`. */
     readonly integratorAccounts?: readonly InstructionKey[];
 }
-/** Build `create_voucher`. */
+/** Build `create_voucher`. Args (Borsh): `name, handle_type, recipient:
+ *  Option<Pubkey>, expires_at: i64, claim_secret_hash: Option<[u8;32]>` — the
+ *  M72 hash is APPENDED LAST. */
 export declare function buildCreateVoucherIx(p: CreateVoucherParams): BuiltInstruction;
 export interface ClaimVoucherParams {
     readonly programId: AddressLike;
@@ -116,8 +145,14 @@ export interface ClaimVoucherParams {
     /** The integrator wallet — REQUIRED iff the voucher carries one; must equal
      *  the voucher's `integrator`. Omit otherwise. */
     readonly integrator?: AddressLike;
+    /** The 32-byte claim secret for an OPEN voucher (M72) — its `sha256` must
+     *  equal the voucher's stored `claim_secret_hash` (else `BadClaimSecret`,
+     *  6105). Read it from the gift link's URL fragment. Null/omit for a bound
+     *  voucher (the program ignores it; sent as Borsh `None`). */
+    readonly claimSecret?: Uint8Array | null;
 }
-/** Build `claim_voucher`. */
+/** Build `claim_voucher`. Args (Borsh): `name, claim_secret: Option<[u8;32]>`
+ *  — the M72 secret is APPENDED LAST. */
 export declare function buildClaimVoucherIx(p: ClaimVoucherParams): BuiltInstruction;
 export interface RefundVoucherParams {
     readonly programId: AddressLike;
@@ -166,6 +201,11 @@ export interface ClaimVoucherTokenizedParams {
     /** The integrator wallet — REQUIRED iff the voucher carries one; must equal
      *  the voucher's `integrator`. Omit otherwise. */
     readonly integrator?: AddressLike;
+    /** The 32-byte claim secret for an OPEN voucher (M72) — its `sha256` must
+     *  equal the voucher's stored `claim_secret_hash` (else `BadClaimSecret`,
+     *  6105). Read it from the gift link's URL fragment. Null/omit for a bound
+     *  voucher (sent as Borsh `None`). */
+    readonly claimSecret?: Uint8Array | null;
 }
 /**
  * Build `claim_voucher_tokenized` (#8335) — the tokenized sibling of

package/dist/voucher.js

@@ -18,11 +18,12 @@
  *
  * # Lifecycle (mirror of lib.rs)
  *
- * - `create_voucher(name, handleType, recipient, expiresAt)` escrows the mint
- *   price (a snapshot of the live price) into `["voucher", name]` and reserves
- *   the voucher slot. `recipient` bound ⇒ the claim registers the handle to
- *   that wallet no matter who submits; `null` ⇒ open-code (the claimer owns
- *   it). An optional integrator referrer (the same trailing accounts as
+ * - `create_voucher(name, handleType, recipient, expiresAt, claimSecretHash)`
+ *   escrows the mint price (a snapshot of the live price) into
+ *   `["voucher", name]` and reserves the voucher slot. `recipient` bound ⇒ the
+ *   claim registers the handle to that wallet no matter who submits; `null` ⇒
+ *   open-code (the claimer owns it) and `claimSecretHash` (= `sha256(secret)`)
+ *   is REQUIRED (M72) — the claimer must present the matching `secret`. An optional integrator referrer (the same trailing accounts as
  *   `register`, from `integrator.ts`) is snapshotted so the claim can split
  *   the escrow. `expiresAt` must be strictly in the future.
  * - `claim_voucher(name)` registers the handle, drawing the fee from the
@@ -74,13 +75,49 @@ function encU64(v) {
     new DataView(out.buffer).setBigInt64(0, v, true);
     return out;
 }
+/** Borsh `Option<[u8;32]>`: tag `0x00` (None) or `0x01 ‖ 32 bytes` (Some) —
+ *  the `claim_secret_hash` on create and the `claim_secret` on claim (M72). */
+function encOption32(v) {
+    if (v === null)
+        return Uint8Array.from([0]);
+    if (v.length !== 32)
+        throw new Error("claim secret / hash must be exactly 32 bytes");
+    const out = new Uint8Array(33);
+    out[0] = 1;
+    out.set(v, 1);
+    return out;
+}
+/**
+ * 32 bytes of fresh CSPRNG output — an OPEN gift voucher's claim secret (M72).
+ * Keep it OUT of the path/query (it belongs in the gift link's URL *fragment*,
+ * which is never sent to a server); its `sha256` ({@link giftSecretHash}) is
+ * what goes on chain as `claim_secret_hash`.
+ */
+export function giftSecret() {
+    return crypto.getRandomValues(new Uint8Array(32));
+}
+/**
+ * `sha256(secret)` — the 32-byte `claim_secret_hash` an OPEN voucher stores at
+ * create and the program recomputes from the claimer's `claim_secret` (M72;
+ * mismatch ⇒ `BadClaimSecret`, 6105). WebCrypto, so async — mirrors
+ * commitReveal's `commitmentHash`.
+ */
+export async function giftSecretHash(secret) {
+    if (secret.length !== 32)
+        throw new Error("gift secret must be exactly 32 bytes");
+    const digest = await crypto.subtle.digest("SHA-256", secret);
+    return new Uint8Array(digest);
+}
 /**
  * Decode a `PrepaidVoucher` account's raw data, or null if not one. Parsed
- * sequentially (Borsh): the two `Option<Pubkey>` fields are 1 byte when
- * absent, 33 when present, so fixed offsets after them would be wrong.
+ * sequentially (Borsh): the two `Option<Pubkey>` fields AND the M72
+ * `Option<[u8;32]> claim_secret_hash` are 1 byte when absent, 33 when present,
+ * so fixed offsets after them would be wrong. `claim_secret_hash` sits AFTER
+ * `created_at` and BEFORE `bump` (+33 bytes at its Some size — the Anchor
+ * INIT_SPACE voucher grew 167 → 200 B).
  */
 export function decodePrepaidVoucher(data) {
-    if (data.length < 8 + 32 + 32 + 1 + 1 + 8 + 1 + 1 + 2 + 8 + 8 + 1)
+    if (data.length < 8 + 32 + 32 + 1 + 1 + 8 + 1 + 1 + 2 + 8 + 8 + 1 + 1)
         return null;
     for (let i = 0; i < 8; i++)
         if (data[i] !== PREPAID_VOUCHER_DISCRIMINATOR[i])
@@ -118,15 +155,25 @@ export function decodePrepaidVoucher(data) {
     o += 8;
     const createdAt = view.getBigInt64(o, true);
     o += 8;
+    const claimSecretTag = data[o];
+    o += 1;
+    let claimSecretHash = null;
+    if (claimSecretTag === 1) {
+        claimSecretHash = data.slice(o, o + 32);
+        o += 32;
+    }
     const bump = data[o];
-    return { payer, name, handleType, amount, recipient, integrator, integratorRateBps, expiresAt, createdAt, bump };
+    return { payer, name, handleType, amount, recipient, integrator, integratorRateBps, expiresAt, createdAt, claimSecretHash, bump };
 }
-/** Build `create_voucher`. */
+/** Build `create_voucher`. Args (Borsh): `name, handle_type, recipient:
+ *  Option<Pubkey>, expires_at: i64, claim_secret_hash: Option<[u8;32]>` — the
+ *  M72 hash is APPENDED LAST. */
 export function buildCreateVoucherIx(p) {
     const name = encString(p.name);
     const recipient = p.recipient ?? null;
     const recBytes = recipient === null ? Uint8Array.from([0]) : Uint8Array.from([1, ...toBytes32(recipient, "recipient")]);
-    const data = new Uint8Array(8 + name.length + 1 + recBytes.length + 8);
+    const hashBytes = encOption32(p.claimSecretHash ?? null);
+    const data = new Uint8Array(8 + name.length + 1 + recBytes.length + 8 + hashBytes.length);
     let o = 0;
     data.set(CREATE_VOUCHER_DISCRIMINATOR, o);
     o += 8;
@@ -137,6 +184,8 @@ export function buildCreateVoucherIx(p) {
     data.set(recBytes, o);
     o += recBytes.length;
     data.set(encU64(BigInt(p.expiresAt)), o);
+    o += 8;
+    data.set(hashBytes, o);
     const keys = [
         { pubkey: toBase58(p.payer, "payer"), isSigner: true, isWritable: true },
         { pubkey: toBase58(p.config, "config"), isSigner: false, isWritable: false },
@@ -148,12 +197,15 @@ export function buildCreateVoucherIx(p) {
         keys.push(...p.integratorAccounts);
     return { programId: toBase58(p.programId, "programId"), keys, data };
 }
-/** Build `claim_voucher`. */
+/** Build `claim_voucher`. Args (Borsh): `name, claim_secret: Option<[u8;32]>`
+ *  — the M72 secret is APPENDED LAST. */
 export function buildClaimVoucherIx(p) {
     const name = encString(p.name);
-    const data = new Uint8Array(8 + name.length);
+    const secretBytes = encOption32(p.claimSecret ?? null);
+    const data = new Uint8Array(8 + name.length + secretBytes.length);
     data.set(CLAIM_VOUCHER_DISCRIMINATOR, 0);
     data.set(name, 8);
+    data.set(secretBytes, 8 + name.length);
     const keys = [
         { pubkey: toBase58(p.claimer, "claimer"), isSigner: true, isWritable: true },
         { pubkey: toBase58(p.config, "config"), isSigner: false, isWritable: true },
@@ -207,9 +259,11 @@ const SYSVAR_INSTRUCTIONS = "Sysvar1nstructions1111111111111111111111111";
  */
 export function buildClaimVoucherTokenizedIx(p) {
     const name = encString(p.name);
-    const data = new Uint8Array(8 + name.length);
+    const secretBytes = encOption32(p.claimSecret ?? null);
+    const data = new Uint8Array(8 + name.length + secretBytes.length);
     data.set(CLAIM_VOUCHER_TOKENIZED_DISCRIMINATOR, 0);
     data.set(name, 8);
+    data.set(secretBytes, 8 + name.length);
     const keys = [
         { pubkey: toBase58(p.claimer, "claimer"), isSigner: true, isWritable: true },
         { pubkey: toBase58(p.config, "config"), isSigner: false, isWritable: true },

package/dist/x402.d.ts

@@ -31,6 +31,18 @@
 /** X1 testnet's x402 network id — CAIP-30 `"solana:" + first 32 chars of the
  *  genesis hash — so unmodified OSS x402 clients route to it (#8325). */
 export declare const X1_TESTNET_NETWORK = "solana:C7ucgdDEhxLTpXHhWSZxavSVmaNTUJWw";
+/** X1 MAINNET's x402 network id — CAIP-30 `"solana:" + first 32 chars of the
+ *  mainnet genesis hash `4SvBP3omtvcCVWdxq1zBY5cDp4wndjsThb6nEMn6iMdN`, so
+ *  unmodified OSS x402 clients route to it. Verified against `getGenesisHash`
+ *  and the live `api.x1id.io` 402 offer. This is the default for
+ *  {@link buildX402Requirements} in this mainnet-era release. */
+export declare const X1_MAINNET_NETWORK = "solana:4SvBP3omtvcCVWdxq1zBY5cDp4wndjsT";
+/** Derive the CAIP-30 x402 network id from a cluster's FULL genesis hash —
+ *  `"solana:" + first 32 base58 chars`. A server that knows its own RPC's
+ *  genesis (the dev-api, the MCP server) should pass the result as the x402
+ *  `network` rather than relying on a compiled-in default, so it is always
+ *  correct for whatever cluster it is actually pointed at. */
+export declare function x402NetworkForGenesis(genesisHash: string): string;
 /** The pre-#8325 `"x1:<full-genesis>"` id. DEPRECATED — kept only so a reader
  *  can still recognise manifests published before the CAIP-30 migration. */
 export declare const X1_LEGACY_TESTNET_NETWORK = "x1:C7ucgdDEhxLTpXHhWSZxavSVmaNTUJWwT5iTdeaviDho";
@@ -96,6 +108,10 @@ export interface BuildX402RequirementsParams {
      *  always set to this same buyer address. Pass the address the caller
      *  expects to pay from. */
     readonly buyer: string;
+    /** CAIP-30 network id. Defaults to {@link X1_MAINNET_NETWORK}; a server on
+     *  another cluster should pass its own — e.g.
+     *  `x402NetworkForGenesis(await rpcGenesisHash)` — rather than rely on the
+     *  default. Pass {@link X1_TESTNET_NETWORK} for testnet. */
     readonly network?: string;
     readonly maxTimeoutSeconds?: number;
     readonly memo?: string;

package/dist/x402.js

@@ -31,6 +31,20 @@
 /** X1 testnet's x402 network id — CAIP-30 `"solana:" + first 32 chars of the
  *  genesis hash — so unmodified OSS x402 clients route to it (#8325). */
 export const X1_TESTNET_NETWORK = "solana:C7ucgdDEhxLTpXHhWSZxavSVmaNTUJWw";
+/** X1 MAINNET's x402 network id — CAIP-30 `"solana:" + first 32 chars of the
+ *  mainnet genesis hash `4SvBP3omtvcCVWdxq1zBY5cDp4wndjsThb6nEMn6iMdN`, so
+ *  unmodified OSS x402 clients route to it. Verified against `getGenesisHash`
+ *  and the live `api.x1id.io` 402 offer. This is the default for
+ *  {@link buildX402Requirements} in this mainnet-era release. */
+export const X1_MAINNET_NETWORK = "solana:4SvBP3omtvcCVWdxq1zBY5cDp4wndjsT";
+/** Derive the CAIP-30 x402 network id from a cluster's FULL genesis hash —
+ *  `"solana:" + first 32 base58 chars`. A server that knows its own RPC's
+ *  genesis (the dev-api, the MCP server) should pass the result as the x402
+ *  `network` rather than relying on a compiled-in default, so it is always
+ *  correct for whatever cluster it is actually pointed at. */
+export function x402NetworkForGenesis(genesisHash) {
+    return "solana:" + genesisHash.slice(0, 32);
+}
 /** The pre-#8325 `"x1:<full-genesis>"` id. DEPRECATED — kept only so a reader
  *  can still recognise manifests published before the CAIP-30 migration. */
 export const X1_LEGACY_TESTNET_NETWORK = "x1:C7ucgdDEhxLTpXHhWSZxavSVmaNTUJWwT5iTdeaviDho";
@@ -63,7 +77,7 @@ export function buildX402Requirements(p) {
     }
     return {
         scheme: X402_SCHEME_EXACT,
-        network: p.network ?? X1_TESTNET_NETWORK,
+        network: p.network ?? X1_MAINNET_NETWORK,
         amount: p.amount,
         asset: p.asset,
         payTo: p.payTo,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x1id/resolve",
-  "version": "0.15.1",
+  "version": "0.17.0",
   "description": "Resolve @handles and X1NS names on X1. Never silently picks between namespaces.",
   "type": "module",
   "main": "./dist/index.js",