@x1id/resolve 0.3.0 → 0.6.0

package/dist/x402.d.ts

@@ -0,0 +1,107 @@
+/**
+ * x402 ("HTTP 402 Payment Required") payment requirements — the pure,
+ * dependency-free half of x1id's x402 support. Types and the
+ * `PaymentRequirements` builder live here; actual transaction construction
+ * and verification need real Solana transaction parsing (`@solana/web3.js`)
+ * and live in `mcp/src/x402/` instead, matching this SDK's established
+ * boundary (zero dependencies, no crypto/serialization — see delegate.ts's
+ * module docs for the same reasoning applied elsewhere).
+ *
+ * Field names and the `"exact"` scheme's wire shape are taken verbatim from
+ * the x402 Foundation's own SVM scheme spec
+ * (x402-foundation/x402, specs/schemes/exact/scheme_exact_svm.md, and the
+ * Go reference implementation under go/mechanisms/svm/exact/), verified
+ * 2026-09-22 — NOT invented. See `docs/x402.md` for the full design,
+ * including what's explicitly OUT of scope here (a facilitator).
+ *
+ * # The one x1id-specific choice: the network identifier
+ *
+ * x402's Solana networks use `"solana:<genesis-hash>"` (CAIP-2-shaped). X1
+ * is SVM-compatible but its OWN chain — not Solana — so it gets its own
+ * namespace under the identical convention: `"x1:<genesis-hash>"`. This is
+ * NOT an x402-foundation-registered network; it's a principled extension of
+ * their own pattern to a new SVM-compatible chain, not a claim of official
+ * support. {@link X1_TESTNET_NETWORK} is the live testnet genesis hash,
+ * verified against `getGenesisHash` 2026-09-22.
+ */
+/** X1 testnet's x402 network identifier (`"x1:<genesis-hash>"`, verified
+ *  live 2026-09-22 via `getGenesisHash`). */
+export declare const X1_TESTNET_NETWORK = "x1:C7ucgdDEhxLTpXHhWSZxavSVmaNTUJWwT5iTdeaviDho";
+/** The x402 scheme x1id implements — "exact": pay a fixed amount of a named
+ *  asset to a named recipient. (x402 also defines "upto" for usage-based
+ *  pricing; not implemented here.) */
+export declare const X402_SCHEME_EXACT = "exact";
+export declare const X402_VERSION = 2;
+/** One entry of a 402 response's `accepts[]` — the SVM `"exact"` scheme's
+ *  `PaymentRequirements`, field names verbatim from the spec. */
+export interface X402PaymentRequirements {
+    readonly scheme: "exact";
+    /** `"x1:<genesis-hash>"` — see the module docs. */
+    readonly network: string;
+    /** Smallest-unit amount, as a DECIMAL STRING (e.g. lamports, or an SPL
+     *  token's atomic units) — never a number (precision). */
+    readonly amount: string;
+    /** The SPL/Token-2022 mint's base58 address. */
+    readonly asset: string;
+    /** The recipient's base58 address (a wallet, not the token account —
+     *  the payer derives the destination ATA from this + `asset`). */
+    readonly payTo: string;
+    readonly maxTimeoutSeconds: number;
+    readonly extra: {
+        /** The sponsor that will co-sign as fee payer, base58. REQUIRED by the
+         *  spec for the client to build a transaction at all — x1id's v1 has
+         *  no sponsor (see docs/x402.md): this SDK always sets it to the
+         *  BUYER's own address (self-sponsored, no facilitator, no custody). */
+        readonly feePayer: string;
+        /** UTF-8, <=256 bytes. Lets a seller correlate the on-chain payment to
+         *  an invoice without a unique deposit address per sale. */
+        readonly memo?: string;
+        readonly recentBlockhash?: string;
+        readonly lastValidBlockHeight?: string;
+    };
+}
+/** The 402 response body's `accepts[]` wrapper — what a resource server
+ *  actually returns. */
+export interface X402PaymentRequiredResponse {
+    readonly x402Version: typeof X402_VERSION;
+    readonly accepts: readonly X402PaymentRequirements[];
+}
+/** What the client sends back (as the `payload.transaction` field, once
+ *  base64-encoded — see `mcp/src/x402/transaction.ts` for actually
+ *  building and encoding one; this type documents the wire shape only). */
+export interface X402PaymentPayload {
+    readonly x402Version: typeof X402_VERSION;
+    readonly accepted: X402PaymentRequirements;
+    readonly payload: {
+        /** Base64-encoded, serialized, partially-signed versioned transaction. */
+        readonly transaction: string;
+    };
+}
+export interface BuildX402RequirementsParams {
+    /** The recipient's base58 address. */
+    readonly payTo: string;
+    /** The SPL/Token-2022 mint's base58 address. */
+    readonly asset: string;
+    /** Smallest-unit amount as a decimal string. */
+    readonly amount: string;
+    /** X1id v1 has no sponsoring facilitator (see the module docs):
+     *  the buyer pays their own transaction fee, so `extra.feePayer` is
+     *  always set to this same buyer address. Pass the address the caller
+     *  expects to pay from. */
+    readonly buyer: string;
+    readonly network?: string;
+    readonly maxTimeoutSeconds?: number;
+    readonly memo?: string;
+    readonly recentBlockhash?: string;
+    readonly lastValidBlockHeight?: string;
+}
+/**
+ * Build one `accepts[]` entry — the resource-server side of a 402 response.
+ * Pure data; does not touch chain, does not fetch a blockhash (pass
+ * `recentBlockhash`/`lastValidBlockHeight` if you have one fresh, or omit
+ * and let the buyer fetch their own — the spec allows either).
+ */
+export declare function buildX402Requirements(p: BuildX402RequirementsParams): X402PaymentRequirements;
+/** Parse a 402 response body, returning null if it doesn't look like one
+ *  (missing/wrong `x402Version`, `accepts` not an array). Never throws. */
+export declare function parseX402Response(body: unknown): X402PaymentRequiredResponse | null;

package/dist/x402.js

@@ -0,0 +1,76 @@
+/**
+ * x402 ("HTTP 402 Payment Required") payment requirements — the pure,
+ * dependency-free half of x1id's x402 support. Types and the
+ * `PaymentRequirements` builder live here; actual transaction construction
+ * and verification need real Solana transaction parsing (`@solana/web3.js`)
+ * and live in `mcp/src/x402/` instead, matching this SDK's established
+ * boundary (zero dependencies, no crypto/serialization — see delegate.ts's
+ * module docs for the same reasoning applied elsewhere).
+ *
+ * Field names and the `"exact"` scheme's wire shape are taken verbatim from
+ * the x402 Foundation's own SVM scheme spec
+ * (x402-foundation/x402, specs/schemes/exact/scheme_exact_svm.md, and the
+ * Go reference implementation under go/mechanisms/svm/exact/), verified
+ * 2026-09-22 — NOT invented. See `docs/x402.md` for the full design,
+ * including what's explicitly OUT of scope here (a facilitator).
+ *
+ * # The one x1id-specific choice: the network identifier
+ *
+ * x402's Solana networks use `"solana:<genesis-hash>"` (CAIP-2-shaped). X1
+ * is SVM-compatible but its OWN chain — not Solana — so it gets its own
+ * namespace under the identical convention: `"x1:<genesis-hash>"`. This is
+ * NOT an x402-foundation-registered network; it's a principled extension of
+ * their own pattern to a new SVM-compatible chain, not a claim of official
+ * support. {@link X1_TESTNET_NETWORK} is the live testnet genesis hash,
+ * verified against `getGenesisHash` 2026-09-22.
+ */
+/** X1 testnet's x402 network identifier (`"x1:<genesis-hash>"`, verified
+ *  live 2026-09-22 via `getGenesisHash`). */
+export const X1_TESTNET_NETWORK = "x1:C7ucgdDEhxLTpXHhWSZxavSVmaNTUJWwT5iTdeaviDho";
+/** The x402 scheme x1id implements — "exact": pay a fixed amount of a named
+ *  asset to a named recipient. (x402 also defines "upto" for usage-based
+ *  pricing; not implemented here.) */
+export const X402_SCHEME_EXACT = "exact";
+export const X402_VERSION = 2;
+/**
+ * Build one `accepts[]` entry — the resource-server side of a 402 response.
+ * Pure data; does not touch chain, does not fetch a blockhash (pass
+ * `recentBlockhash`/`lastValidBlockHeight` if you have one fresh, or omit
+ * and let the buyer fetch their own — the spec allows either).
+ */
+export function buildX402Requirements(p) {
+    if (!/^\d+$/.test(p.amount)) {
+        throw new Error("amount must be a decimal string of smallest units (e.g. \"1000000\")");
+    }
+    if (p.memo !== undefined && new TextEncoder().encode(p.memo).length > 256) {
+        throw new Error("memo must be <=256 UTF-8 bytes");
+    }
+    const extra = { feePayer: p.buyer };
+    if (p.memo !== undefined)
+        extra.memo = p.memo;
+    if (p.recentBlockhash !== undefined) {
+        extra.recentBlockhash = p.recentBlockhash;
+    }
+    if (p.lastValidBlockHeight !== undefined) {
+        extra.lastValidBlockHeight = p.lastValidBlockHeight;
+    }
+    return {
+        scheme: X402_SCHEME_EXACT,
+        network: p.network ?? X1_TESTNET_NETWORK,
+        amount: p.amount,
+        asset: p.asset,
+        payTo: p.payTo,
+        maxTimeoutSeconds: p.maxTimeoutSeconds ?? 60,
+        extra,
+    };
+}
+/** Parse a 402 response body, returning null if it doesn't look like one
+ *  (missing/wrong `x402Version`, `accepts` not an array). Never throws. */
+export function parseX402Response(body) {
+    if (typeof body !== "object" || body === null)
+        return null;
+    const b = body;
+    if (b.x402Version !== X402_VERSION || !Array.isArray(b.accepts))
+        return null;
+    return { x402Version: X402_VERSION, accepts: b.accepts };
+}

package/package.json

@@ -1,34 +1,70 @@
 {
   "name": "@x1id/resolve",
-  "version": "0.3.0",
+  "version": "0.6.0",
   "description": "Resolve @handles and X1NS names on X1. Never silently picks between namespaces.",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
-    ".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" },
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
     "./wasm/x1_resolve_wasm.wasm": "./wasm/x1_resolve_wasm.wasm",
     "./wasm/*": "./wasm/*",
     "./package.json": "./package.json"
   },
-  "files": ["dist", "wasm", "README.md"],
+  "files": [
+    "dist",
+    "wasm",
+    "schema",
+    "README.md"
+  ],
   "scripts": {
     "build:wasm": "cargo build --release -p x1-resolve-wasm --target wasm32-unknown-unknown && cp target/wasm32-unknown-unknown/release/x1_resolve_wasm.wasm wasm/",
     "build": "tsc -p tsconfig.json",
     "test": "node --test test/*.test.js",
     "lint:package": "publint",
-    "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"
+    "prepublishOnly": "npm run build"
   },
-  "keywords": ["x1", "x1id", "solana", "svm", "naming", "x1ns", "handles", "wallet", "resolver", "web3"],
+  "keywords": [
+    "x1",
+    "x1id",
+    "solana",
+    "svm",
+    "naming",
+    "x1ns",
+    "handles",
+    "wallet",
+    "resolver",
+    "web3"
+  ],
   "homepage": "https://x1id.io",
   "license": "MIT",
-  "publishConfig": { "access": "public" },
-  "engines": { "node": ">=18" },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
   "devDependencies": {
     "typescript": "^5.6.0",
     "@types/node": "^22.0.0",
     "publint": "^0.2.0"
   },
-  "peerDependencies": { "@solana/web3.js": "^1.95.0" },
-  "peerDependenciesMeta": { "@solana/web3.js": { "optional": true } }
+  "peerDependencies": {
+    "@solana/web3.js": "^1.95.0"
+  },
+  "peerDependenciesMeta": {
+    "@solana/web3.js": {
+      "optional": true
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fortiblox/x1id-sdk.git"
+  },
+  "bugs": {
+    "url": "https://x1id.io"
+  }
 }

package/schema/agent-manifest.json

@@ -0,0 +1,91 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://x1id.io/schema/agent-manifest.json",
+  "title": "x1id agent manifest",
+  "description": "A machine-readable description of an @handle operating as an AI agent — what it does, how to reach it, and how to pay it. Nothing here is a payment fact: payment.addresses[] is a mirror of the on-chain address Record(s) and payment.x402 is a pre-flight hint; the chain and the live 402 response always win. See docs/agent-records.md.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["x1id"],
+  "properties": {
+    "x1id": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["version", "name", "network", "handle"],
+      "properties": {
+        "version": { "const": 1 },
+        "name": { "type": "string", "minLength": 1, "maxLength": 260, "description": "The canonical @handle name, without the @." },
+        "network": { "type": "string", "enum": ["testnet", "mainnet"] },
+        "handle": { "type": "string", "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "The Handle PDA account address, base58 — the uniqueness anchor. A manifest served for the wrong name/handle is discarded on read." }
+      }
+    },
+    "identity": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "attestation": { "type": "string", "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Base58 address of a non-stale Attestation account on this handle (kind DNS or SOCIAL). See docs/agent-records.md §4 for what L1 does and does not prove." },
+        "description": { "type": "string", "maxLength": 2048 }
+      }
+    },
+    "endpoints": {
+      "type": "array",
+      "maxItems": 32,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["type", "url"],
+        "properties": {
+          "type": { "type": "string", "enum": ["x402", "mcp", "a2a", "http"] },
+          "url": { "$ref": "#/$defs/HttpsUrl" }
+        }
+      }
+    },
+    "capabilities": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["url"],
+      "properties": {
+        "schema": { "$ref": "#/$defs/HttpsUrl" },
+        "url": { "$ref": "#/$defs/HttpsUrl" }
+      }
+    },
+    "payment": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "addresses": {
+          "type": "array",
+          "maxItems": 16,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["coinType", "address"],
+            "properties": {
+              "coinType": { "type": "integer", "minimum": 0 },
+              "address": { "type": "string", "minLength": 1, "maxLength": 128 },
+              "verified": { "type": "boolean" }
+            }
+          }
+        },
+        "x402": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["network"],
+          "properties": {
+            "network": { "type": "string", "minLength": 1, "description": "e.g. \"x1-testnet\" or \"x1-mainnet\" — an x1id-defined network tag, not a CAIP-2 EVM chain id." },
+            "asset": { "type": "string", "maxLength": 128 },
+            "scheme": { "type": "string", "minLength": 1, "maxLength": 32 },
+            "facilitator": { "$ref": "#/$defs/HttpsUrl" },
+            "extra": { "type": "object" }
+          }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "HttpsUrl": {
+      "type": "string",
+      "pattern": "^https://[^\\s@/]+(/[^\\s]*)?$",
+      "maxLength": 2048
+    }
+  }
+}