@x1id/resolve 0.2.0 → 0.3.0

package/dist/voucher.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Prepaid gift-registration vouchers (`PrepaidVoucher`, #7399): instruction
+ * builders and account decoding for `create_voucher` / `claim_voucher` /
+ * `refund_voucher`.
+ *
+ * Hand-rolled like the rest of this package — see `delegate.ts` for the
+ * web3.js adapter and `wasm.ts` for why PDAs are derived by the caller, not
+ * here.
+ *
+ * # Deriving the PDAs
+ *
+ * ```ts
+ * // the voucher itself
+ * PublicKey.findProgramAddressSync([Buffer.from(VOUCHER_SEED), Buffer.from(name)], programId);
+ * // the handle the claim will register (canonical name bytes)
+ * PublicKey.findProgramAddressSync([Buffer.from("handle"), Buffer.from(name)], programId);
+ * ```
+ *
+ * # 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
+ *   `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
+ *   escrow (split integrator/treasury per the snapshot), and closes the
+ *   voucher — rent back to the original payer. The `claimer` pays only the tx
+ *   fee and the handle's rent, never the mint fee; a relayer may claim for a
+ *   bound recipient. Supply the integrator wallet iff the voucher carries one.
+ * - `refund_voucher(name)` returns the whole escrow (+ rent) to the payer,
+ *   payer-signed, only at/after `expiresAt`.
+ */
+import type { AddressLike, BuiltInstruction, InstructionKey } from "./delegate.js";
+/** Seed prefix of the voucher PDA: `["voucher", name]`. */
+export declare const VOUCHER_SEED = "voucher";
+/** Anchor instruction discriminator `sha256("global:create_voucher")[0..8]`. */
+export declare const CREATE_VOUCHER_DISCRIMINATOR: Uint8Array;
+/** Anchor instruction discriminator `sha256("global:claim_voucher")[0..8]`. */
+export declare const CLAIM_VOUCHER_DISCRIMINATOR: Uint8Array;
+/** Anchor instruction discriminator `sha256("global:refund_voucher")[0..8]`. */
+export declare const REFUND_VOUCHER_DISCRIMINATOR: Uint8Array;
+/** Anchor account discriminator `sha256("account:PrepaidVoucher")[0..8]`. */
+export declare const PREPAID_VOUCHER_DISCRIMINATOR: Uint8Array;
+/** `HandleType` (state.rs): descriptive only, does not gate anything. */
+export declare const HandleType: {
+    readonly Human: 0;
+    readonly Merchant: 1;
+    readonly Org: 2;
+    readonly Agent: 3;
+};
+export type HandleTypeValue = (typeof HandleType)[keyof typeof HandleType];
+/** Decoded `PrepaidVoucher` account. */
+export interface PrepaidVoucher {
+    /** Who funded it and gets the refund (base58). */
+    readonly payer: string;
+    /** Canonical name (no `@`). */
+    readonly name: string;
+    readonly handleType: number;
+    /** Escrowed mint fee, in lamports. */
+    readonly amount: bigint;
+    /** Bound recipient (base58) or null for an open-code voucher. */
+    readonly recipient: string | null;
+    /** Integrator referrer (base58) or null. */
+    readonly integrator: string | null;
+    /** Integrator share in basis points (meaningful only if `integrator`). */
+    readonly integratorRateBps: number;
+    readonly expiresAt: bigint;
+    readonly createdAt: bigint;
+    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.
+ */
+export declare function decodePrepaidVoucher(data: Uint8Array): PrepaidVoucher | null;
+export interface CreateVoucherParams {
+    readonly programId: AddressLike;
+    /** Funds the escrow + the voucher's rent. Signer. */
+    readonly payer: AddressLike;
+    /** The `["config"]` PDA. */
+    readonly config: AddressLike;
+    /** The `["voucher", name]` PDA. */
+    readonly voucher: AddressLike;
+    /** The `["handle", name]` PDA — must be unregistered. */
+    readonly handle: AddressLike;
+    /** Canonical name (no `@`). */
+    readonly name: string;
+    readonly handleType: HandleTypeValue;
+    /** Bind the gift to this wallet, or null for open-code. */
+    readonly recipient?: AddressLike | null;
+    /** Unix seconds; must be strictly in the future. */
+    readonly expiresAt: bigint | number;
+    /** Optional integrator pair from `integratorAccountsForCreateVoucher`. */
+    readonly integratorAccounts?: readonly InstructionKey[];
+}
+/** Build `create_voucher`. */
+export declare function buildCreateVoucherIx(p: CreateVoucherParams): BuiltInstruction;
+export interface ClaimVoucherParams {
+    readonly programId: AddressLike;
+    /** Pays the tx fee + the handle's rent (NOT the mint fee). Signer. May be a
+     *  relayer when the voucher binds a recipient. */
+    readonly claimer: AddressLike;
+    readonly config: AddressLike;
+    /** `Config.treasury`. */
+    readonly treasury: AddressLike;
+    readonly voucher: AddressLike;
+    /** The voucher's recorded payer — receives the voucher's rent on close. */
+    readonly voucherPayer: AddressLike;
+    /** The `["handle", name]` PDA being registered. */
+    readonly handle: AddressLike;
+    readonly name: string;
+    /** The integrator wallet — REQUIRED iff the voucher carries one; must equal
+     *  the voucher's `integrator`. Omit otherwise. */
+    readonly integrator?: AddressLike;
+}
+/** Build `claim_voucher`. */
+export declare function buildClaimVoucherIx(p: ClaimVoucherParams): BuiltInstruction;
+export interface RefundVoucherParams {
+    readonly programId: AddressLike;
+    /** The original payer. Signer; receives escrow + rent. */
+    readonly payer: AddressLike;
+    readonly voucher: AddressLike;
+    readonly name: string;
+}
+/** Build `refund_voucher` — payer-signed, only valid at/after `expiresAt`. */
+export declare function buildRefundVoucherIx(p: RefundVoucherParams): BuiltInstruction;

package/dist/voucher.js

@@ -0,0 +1,185 @@
+/**
+ * Prepaid gift-registration vouchers (`PrepaidVoucher`, #7399): instruction
+ * builders and account decoding for `create_voucher` / `claim_voucher` /
+ * `refund_voucher`.
+ *
+ * Hand-rolled like the rest of this package — see `delegate.ts` for the
+ * web3.js adapter and `wasm.ts` for why PDAs are derived by the caller, not
+ * here.
+ *
+ * # Deriving the PDAs
+ *
+ * ```ts
+ * // the voucher itself
+ * PublicKey.findProgramAddressSync([Buffer.from(VOUCHER_SEED), Buffer.from(name)], programId);
+ * // the handle the claim will register (canonical name bytes)
+ * PublicKey.findProgramAddressSync([Buffer.from("handle"), Buffer.from(name)], programId);
+ * ```
+ *
+ * # 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
+ *   `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
+ *   escrow (split integrator/treasury per the snapshot), and closes the
+ *   voucher — rent back to the original payer. The `claimer` pays only the tx
+ *   fee and the handle's rent, never the mint fee; a relayer may claim for a
+ *   bound recipient. Supply the integrator wallet iff the voucher carries one.
+ * - `refund_voucher(name)` returns the whole escrow (+ rent) to the payer,
+ *   payer-signed, only at/after `expiresAt`.
+ */
+import { encodeBase58, decodeBase58_32 } from "./base58.js";
+/** Seed prefix of the voucher PDA: `["voucher", name]`. */
+export const VOUCHER_SEED = "voucher";
+/** Anchor instruction discriminator `sha256("global:create_voucher")[0..8]`. */
+export const CREATE_VOUCHER_DISCRIMINATOR = Uint8Array.from([22, 97, 32, 21, 104, 137, 188, 143]);
+/** Anchor instruction discriminator `sha256("global:claim_voucher")[0..8]`. */
+export const CLAIM_VOUCHER_DISCRIMINATOR = Uint8Array.from([229, 30, 138, 35, 188, 87, 230, 7]);
+/** Anchor instruction discriminator `sha256("global:refund_voucher")[0..8]`. */
+export const REFUND_VOUCHER_DISCRIMINATOR = Uint8Array.from([27, 159, 115, 120, 212, 202, 186, 248]);
+/** Anchor account discriminator `sha256("account:PrepaidVoucher")[0..8]`. */
+export const PREPAID_VOUCHER_DISCRIMINATOR = Uint8Array.from([159, 185, 203, 226, 62, 6, 57, 194]);
+/** `HandleType` (state.rs): descriptive only, does not gate anything. */
+export const HandleType = { Human: 0, Merchant: 1, Org: 2, Agent: 3 };
+const SYSTEM_PROGRAM = "11111111111111111111111111111111";
+function toBytes32(v, what) {
+    if (typeof v === "string") {
+        const b = decodeBase58_32(v);
+        if (!b)
+            throw new Error(`${what} is not a valid base58 address`);
+        return b;
+    }
+    if (v.length !== 32)
+        throw new Error(`${what} must be exactly 32 bytes`);
+    return v;
+}
+function toBase58(v, what) {
+    return encodeBase58(toBytes32(v, what));
+}
+/** Borsh `String`: u32 LE length + UTF-8 bytes. */
+function encString(s) {
+    const bytes = new TextEncoder().encode(s);
+    const out = new Uint8Array(4 + bytes.length);
+    new DataView(out.buffer).setUint32(0, bytes.length, true);
+    out.set(bytes, 4);
+    return out;
+}
+function encU64(v) {
+    const out = new Uint8Array(8);
+    new DataView(out.buffer).setBigInt64(0, v, true);
+    return out;
+}
+/**
+ * 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.
+ */
+export function decodePrepaidVoucher(data) {
+    if (data.length < 8 + 32 + 32 + 1 + 1 + 8 + 1 + 1 + 2 + 8 + 8 + 1)
+        return null;
+    for (let i = 0; i < 8; i++)
+        if (data[i] !== PREPAID_VOUCHER_DISCRIMINATOR[i])
+            return null;
+    const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+    let o = 8;
+    const payer = encodeBase58(data.slice(o, o + 32));
+    o += 32;
+    const nameBytes = data.slice(o, o + 32);
+    o += 32;
+    const nameLen = data[o];
+    o += 1;
+    const name = new TextDecoder().decode(nameBytes.slice(0, nameLen));
+    const handleType = data[o];
+    o += 1;
+    const amount = view.getBigUint64(o, true);
+    o += 8;
+    const recipientTag = data[o];
+    o += 1;
+    let recipient = null;
+    if (recipientTag === 1) {
+        recipient = encodeBase58(data.slice(o, o + 32));
+        o += 32;
+    }
+    const integratorTag = data[o];
+    o += 1;
+    let integrator = null;
+    if (integratorTag === 1) {
+        integrator = encodeBase58(data.slice(o, o + 32));
+        o += 32;
+    }
+    const integratorRateBps = view.getUint16(o, true);
+    o += 2;
+    const expiresAt = view.getBigInt64(o, true);
+    o += 8;
+    const createdAt = view.getBigInt64(o, true);
+    o += 8;
+    const bump = data[o];
+    return { payer, name, handleType, amount, recipient, integrator, integratorRateBps, expiresAt, createdAt, bump };
+}
+/** Build `create_voucher`. */
+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);
+    let o = 0;
+    data.set(CREATE_VOUCHER_DISCRIMINATOR, o);
+    o += 8;
+    data.set(name, o);
+    o += name.length;
+    data[o] = p.handleType;
+    o += 1;
+    data.set(recBytes, o);
+    o += recBytes.length;
+    data.set(encU64(BigInt(p.expiresAt)), o);
+    const keys = [
+        { pubkey: toBase58(p.payer, "payer"), isSigner: true, isWritable: true },
+        { pubkey: toBase58(p.config, "config"), isSigner: false, isWritable: false },
+        { pubkey: toBase58(p.voucher, "voucher"), isSigner: false, isWritable: true },
+        { pubkey: toBase58(p.handle, "handle"), isSigner: false, isWritable: false },
+        { pubkey: SYSTEM_PROGRAM, isSigner: false, isWritable: false },
+    ];
+    if (p.integratorAccounts)
+        keys.push(...p.integratorAccounts);
+    return { programId: toBase58(p.programId, "programId"), keys, data };
+}
+/** Build `claim_voucher`. */
+export function buildClaimVoucherIx(p) {
+    const name = encString(p.name);
+    const data = new Uint8Array(8 + name.length);
+    data.set(CLAIM_VOUCHER_DISCRIMINATOR, 0);
+    data.set(name, 8);
+    const keys = [
+        { pubkey: toBase58(p.claimer, "claimer"), isSigner: true, isWritable: true },
+        { pubkey: toBase58(p.config, "config"), isSigner: false, isWritable: true },
+        { pubkey: toBase58(p.treasury, "treasury"), isSigner: false, isWritable: true },
+        { pubkey: toBase58(p.voucher, "voucher"), isSigner: false, isWritable: true },
+        { pubkey: toBase58(p.voucherPayer, "voucherPayer"), isSigner: false, isWritable: true },
+        { pubkey: toBase58(p.handle, "handle"), isSigner: false, isWritable: true },
+        { pubkey: SYSTEM_PROGRAM, isSigner: false, isWritable: false },
+    ];
+    if (p.integrator !== undefined) {
+        keys.push({ pubkey: toBase58(p.integrator, "integrator"), isSigner: false, isWritable: true });
+    }
+    return { programId: toBase58(p.programId, "programId"), keys, data };
+}
+/** Build `refund_voucher` — payer-signed, only valid at/after `expiresAt`. */
+export function buildRefundVoucherIx(p) {
+    const name = encString(p.name);
+    const data = new Uint8Array(8 + name.length);
+    data.set(REFUND_VOUCHER_DISCRIMINATOR, 0);
+    data.set(name, 8);
+    return {
+        programId: toBase58(p.programId, "programId"),
+        keys: [
+            { pubkey: toBase58(p.payer, "payer"), isSigner: true, isWritable: true },
+            { pubkey: toBase58(p.voucher, "voucher"), isSigner: false, isWritable: true },
+        ],
+        data,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x1id/resolve",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Resolve @handles and X1NS names on X1. Never silently picks between namespaces.",
   "type": "module",
   "main": "./dist/index.js",
@@ -17,7 +17,7 @@
     "build": "tsc -p tsconfig.json",
     "test": "node --test test/*.test.js",
     "lint:package": "publint",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "cargo build --release -p x1-resolve-wasm --target wasm32-unknown-unknown --manifest-path ../Cargo.toml && node ../web/verify-wasm.mjs wasm/x1_resolve_wasm.wasm ../target/wasm32-unknown-unknown/release/x1_resolve_wasm.wasm && npm run build"
   },
   "keywords": ["x1", "x1id", "solana", "svm", "naming", "x1ns", "handles", "wallet", "resolver", "web3"],
   "homepage": "https://x1id.io",

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 Fortiblox
-
-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.