@leashmarket/core 0.1.0

package/README.md

@@ -0,0 +1,32 @@
+# @leashmarket/core
+
+Policy evaluation, receipt hashing / chain verification, real x402 client
+adapter for Solana, treasury helpers, and an env-based kill-switch.
+
+```ts
+import {
+  evaluate,
+  finalizeReceipt,
+  verifyReceiptChain,
+  treasuryPda,
+  readPauseFromEnv,
+} from '@leashmarket/core';
+import { createSvmBuyerFetch } from '@leashmarket/core/x402';
+```
+
+`createSvmBuyerFetch({ signer, networks, rpcUrl })` registers
+`ExactSvmScheme` (from `@x402/svm`) with `wrapFetchWithPayment` (from
+`@x402/fetch`) and returns a `paidFetch` that handles the real x402
+402 → sign SPL transfer → retry → settle round-trip on Solana.
+
+All hashing uses `@noble/hashes` so the package runs unchanged in Node,
+the browser, and edge runtimes.
+
+## Test
+
+```bash
+pnpm --filter @leashmarket/core test
+```
+
+See the [`Real x402 on Solana`](../../apps/docs/standards/x402-on-solana.mdx)
+doc for the protocol-level walkthrough.

package/dist/agent/agent.d.ts

@@ -0,0 +1,8 @@
+import type { Context, PublicKey } from '@metaplex-foundation/umi';
+export declare class Agent {
+    readonly asset: PublicKey;
+    constructor(asset: string | PublicKey);
+    /** Asset Signer PDA (treasury) — requires Umi context for PDA derivation. */
+    treasuryPda(umi: Pick<Context, 'eddsa' | 'programs'>): PublicKey;
+}
+//# sourceMappingURL=agent.d.ts.map

package/dist/agent/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/agent/agent.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAGnE,qBAAa,KAAK;IAChB,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;gBAEd,KAAK,EAAE,MAAM,GAAG,SAAS;IAIrC,6EAA6E;IAC7E,WAAW,CAAC,GAAG,EAAE,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,UAAU,CAAC,GAAG,SAAS;CAIjE"}

package/dist/agent/agent.js

@@ -0,0 +1,14 @@
+import { findAssetSignerPda } from '@metaplex-foundation/mpl-core';
+import { publicKey } from '@metaplex-foundation/umi';
+export class Agent {
+    asset;
+    constructor(asset) {
+        this.asset = typeof asset === 'string' ? publicKey(asset) : asset;
+    }
+    /** Asset Signer PDA (treasury) — requires Umi context for PDA derivation. */
+    treasuryPda(umi) {
+        const [address] = findAssetSignerPda(umi, { asset: this.asset });
+        return address;
+    }
+}
+//# sourceMappingURL=agent.js.map

package/dist/agent/agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../src/agent/agent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AAEnE,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAErD,MAAM,OAAO,KAAK;IACP,KAAK,CAAY;IAE1B,YAAY,KAAyB;QACnC,IAAI,CAAC,KAAK,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;IACpE,CAAC;IAED,6EAA6E;IAC7E,WAAW,CAAC,GAAwC;QAClD,MAAM,CAAC,OAAO,CAAC,GAAG,kBAAkB,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;QACjE,OAAO,OAAO,CAAC;IACjB,CAAC;CACF"}

package/dist/agent/treasury-pda.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Kit-native helpers to derive the agent treasury (Asset Signer PDA) and the
+ * treasury's SPL token ATA for a given mint. These mirror what `mpl-core`'s
+ * `findAssetSignerPda` does (seeds = `["mpl-core-execute", asset]`, program =
+ * `CoREENxT6tW1HoK8ypY1SxRMZTcVPm7R94rH4PZNhX7d`) but using `@solana/kit`
+ * primitives so consumers (e.g. `@leashmarket/buyer-kit`) can derive the source
+ * token account without dragging in the Umi runtime.
+ *
+ * Used by `createBuyer` to surface precise pre-flight failure reasons
+ * (`insufficient_balance`, `insufficient_allowance`, `no_delegate`, etc.)
+ * even when the caller didn't pre-cache the source ATA.
+ */
+import { type Address } from '@solana/kit';
+import { TOKEN_2022_PROGRAM_ADDRESS } from '@solana-program/token-2022';
+import { TOKEN_PROGRAM_ADDRESS } from '@solana-program/token';
+/** Metaplex Core program ID — owns the Asset Signer PDA. */
+export declare const MPL_CORE_PROGRAM_ADDRESS: Address;
+/**
+ * Derive the agent treasury (Asset Signer PDA) for a Metaplex Core asset.
+ *
+ * Seeds match the on-chain program: `["mpl-core-execute", asset_pubkey]`.
+ * Wire-compatible with `@metaplex-foundation/mpl-core`'s
+ * {@link findAssetSignerPda} but Umi-free.
+ */
+export declare function deriveAgentTreasuryAddress(asset: string | Address): Promise<Address>;
+/**
+ * Derive the treasury's Associated Token Account for `mint`.
+ *
+ * `tokenProgram` is the SPL token program that owns this mint. **Pass it
+ * explicitly whenever the mint may be Token-2022** (e.g. USDG); the legacy
+ * default below is only correct for USDC + USDT. Helpers like
+ * {@link tokenProgramForMint} resolve this from the static stable catalog so
+ * callers don't have to spell out program addresses.
+ *
+ * Defaulting to the legacy program is intentional: an unknown mint is far
+ * more likely to be a vanilla SPL token than Token-2022, and a wrong default
+ * here surfaces as a clean `ata_missing` rather than a malformed transfer.
+ */
+export declare function deriveAgentTreasuryAta(args: {
+    asset: string | Address;
+    mint: string | Address;
+    tokenProgram?: Address;
+}): Promise<{
+    treasury: Address;
+    ata: Address;
+}>;
+/** Re-export common token program addresses so consumers don't have to depend on both `@solana-program/*` packages. */
+export { TOKEN_PROGRAM_ADDRESS, TOKEN_2022_PROGRAM_ADDRESS };
+//# sourceMappingURL=treasury-pda.d.ts.map

package/dist/agent/treasury-pda.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"treasury-pda.d.ts","sourceRoot":"","sources":["../../src/agent/treasury-pda.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAIL,KAAK,OAAO,EACb,MAAM,aAAa,CAAC;AACrB,OAAO,EAA0B,0BAA0B,EAAE,MAAM,4BAA4B,CAAC;AAChG,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAE9D,4DAA4D;AAC5D,eAAO,MAAM,wBAAwB,EAEhC,OAAO,CAAC;AAEb;;;;;;GAMG;AACH,wBAAsB,0BAA0B,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAO1F;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,sBAAsB,CAAC,IAAI,EAAE;IACjD,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;IACxB,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IACvB,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB,GAAG,OAAO,CAAC;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,GAAG,EAAE,OAAO,CAAA;CAAE,CAAC,CAM/C;AAED,uHAAuH;AACvH,OAAO,EAAE,qBAAqB,EAAE,0BAA0B,EAAE,CAAC"}

package/dist/agent/treasury-pda.js

@@ -0,0 +1,55 @@
+/**
+ * Kit-native helpers to derive the agent treasury (Asset Signer PDA) and the
+ * treasury's SPL token ATA for a given mint. These mirror what `mpl-core`'s
+ * `findAssetSignerPda` does (seeds = `["mpl-core-execute", asset]`, program =
+ * `CoREENxT6tW1HoK8ypY1SxRMZTcVPm7R94rH4PZNhX7d`) but using `@solana/kit`
+ * primitives so consumers (e.g. `@leashmarket/buyer-kit`) can derive the source
+ * token account without dragging in the Umi runtime.
+ *
+ * Used by `createBuyer` to surface precise pre-flight failure reasons
+ * (`insufficient_balance`, `insufficient_allowance`, `no_delegate`, etc.)
+ * even when the caller didn't pre-cache the source ATA.
+ */
+import { address as toAddress, getAddressEncoder, getProgramDerivedAddress, } from '@solana/kit';
+import { findAssociatedTokenPda, TOKEN_2022_PROGRAM_ADDRESS } from '@solana-program/token-2022';
+import { TOKEN_PROGRAM_ADDRESS } from '@solana-program/token';
+/** Metaplex Core program ID — owns the Asset Signer PDA. */
+export const MPL_CORE_PROGRAM_ADDRESS = toAddress('CoREENxT6tW1HoK8ypY1SxRMZTcVPm7R94rH4PZNhX7d');
+/**
+ * Derive the agent treasury (Asset Signer PDA) for a Metaplex Core asset.
+ *
+ * Seeds match the on-chain program: `["mpl-core-execute", asset_pubkey]`.
+ * Wire-compatible with `@metaplex-foundation/mpl-core`'s
+ * {@link findAssetSignerPda} but Umi-free.
+ */
+export async function deriveAgentTreasuryAddress(asset) {
+    const assetAddress = typeof asset === 'string' ? toAddress(asset) : asset;
+    const [pda] = await getProgramDerivedAddress({
+        programAddress: MPL_CORE_PROGRAM_ADDRESS,
+        seeds: [new TextEncoder().encode('mpl-core-execute'), getAddressEncoder().encode(assetAddress)],
+    });
+    return pda;
+}
+/**
+ * Derive the treasury's Associated Token Account for `mint`.
+ *
+ * `tokenProgram` is the SPL token program that owns this mint. **Pass it
+ * explicitly whenever the mint may be Token-2022** (e.g. USDG); the legacy
+ * default below is only correct for USDC + USDT. Helpers like
+ * {@link tokenProgramForMint} resolve this from the static stable catalog so
+ * callers don't have to spell out program addresses.
+ *
+ * Defaulting to the legacy program is intentional: an unknown mint is far
+ * more likely to be a vanilla SPL token than Token-2022, and a wrong default
+ * here surfaces as a clean `ata_missing` rather than a malformed transfer.
+ */
+export async function deriveAgentTreasuryAta(args) {
+    const treasury = await deriveAgentTreasuryAddress(args.asset);
+    const mint = typeof args.mint === 'string' ? toAddress(args.mint) : args.mint;
+    const tokenProgram = args.tokenProgram ?? TOKEN_PROGRAM_ADDRESS;
+    const [ata] = await findAssociatedTokenPda({ mint, owner: treasury, tokenProgram });
+    return { treasury, ata };
+}
+/** Re-export common token program addresses so consumers don't have to depend on both `@solana-program/*` packages. */
+export { TOKEN_PROGRAM_ADDRESS, TOKEN_2022_PROGRAM_ADDRESS };
+//# sourceMappingURL=treasury-pda.js.map

package/dist/agent/treasury-pda.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"treasury-pda.js","sourceRoot":"","sources":["../../src/agent/treasury-pda.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EACL,OAAO,IAAI,SAAS,EACpB,iBAAiB,EACjB,wBAAwB,GAEzB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,sBAAsB,EAAE,0BAA0B,EAAE,MAAM,4BAA4B,CAAC;AAChG,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAE9D,4DAA4D;AAC5D,MAAM,CAAC,MAAM,wBAAwB,GAAG,SAAS,CAC/C,8CAA8C,CACpC,CAAC;AAEb;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAAC,KAAuB;IACtE,MAAM,YAAY,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAE,SAAS,CAAC,KAAK,CAAa,CAAC,CAAC,CAAC,KAAK,CAAC;IACvF,MAAM,CAAC,GAAG,CAAC,GAAG,MAAM,wBAAwB,CAAC;QAC3C,cAAc,EAAE,wBAAwB;QACxC,KAAK,EAAE,CAAC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,kBAAkB,CAAC,EAAE,iBAAiB,EAAE,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;KAChG,CAAC,CAAC;IACH,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,IAI5C;IACC,MAAM,QAAQ,GAAG,MAAM,0BAA0B,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC9D,MAAM,IAAI,GAAG,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAE,SAAS,CAAC,IAAI,CAAC,IAAI,CAAa,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;IAC3F,MAAM,YAAY,GAAG,IAAI,CAAC,YAAY,IAAI,qBAAqB,CAAC;IAChE,MAAM,CAAC,GAAG,CAAC,GAAG,MAAM,sBAAsB,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,CAAC,CAAC;IACpF,OAAO,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC;AAC3B,CAAC;AAED,uHAAuH;AACvH,OAAO,EAAE,qBAAqB,EAAE,0BAA0B,EAAE,CAAC"}

package/dist/explorer/index.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Explorer URL builders for Solana addresses, transactions, and Metaplex
+ * Core agent assets. Used by Leash to stamp `tx_explorer` /
+ * `agent_explorer` links into x402 response headers and to render "View on
+ * Solscan" affordances in the playground UI.
+ *
+ * We default to Solscan (best UX for SPL transfers and Core assets) but
+ * support `solana-explorer` (the official explorer.solana.com) as well.
+ */
+import type { TokenNetwork } from '../tokens/index.js';
+export type ExplorerProvider = 'solscan' | 'solana-explorer';
+export type ExplorerOptions = {
+    /** Defaults to `'devnet'`. Mainnet links omit the `?cluster=` param. */
+    network?: TokenNetwork;
+    /** Defaults to `'solscan'`. */
+    provider?: ExplorerProvider;
+};
+/**
+ * Explorer page for an SPL token transfer / x402 settlement. Returns
+ * `null` when no signature is supplied so callers can pipe through `null`
+ * fields from receipts without nullish-checking inline.
+ */
+export declare function transactionExplorerUrl(signature: string | null | undefined, opts?: ExplorerOptions): string | null;
+/** Explorer page for a Metaplex Core agent asset (the agent mint address). */
+export declare function agentExplorerUrl(mint: string | null | undefined, opts?: ExplorerOptions): string | null;
+/** Explorer page for any Solana account / mint / PDA. */
+export declare function addressExplorerUrl(address: string | null | undefined, opts?: ExplorerOptions): string | null;
+/**
+ * Default base for the Leash protocol explorer. Override via the
+ * `baseUrl` option (or `LEASH_EXPLORER_URL` upstream) when running
+ * against a self-hosted explorer or a staging deployment.
+ */
+export declare const LEASH_EXPLORER_DEFAULT = "https://explorer.leash.market";
+/**
+ * Page on `explorer.leash.market` for a Leash receipt hash. Returns
+ * `null` when no hash is supplied so callers can pipe through nullable
+ * fields without inline checks.
+ *
+ * The hash should be the seller-side (canonical) `receipt_hash` — the
+ * one stamped on the response via `X-Leash-Receipt-Hash`. The
+ * buyer-kit's locally-computed hash is per-buyer-view and the explorer
+ * does not index it.
+ */
+export declare function leashReceiptUrl(hash: string | null | undefined, opts?: {
+    baseUrl?: string;
+}): string | null;
+/** Page on `explorer.leash.market` for a Solana tx signature. */
+export declare function leashTxUrl(signature: string | null | undefined, opts?: {
+    baseUrl?: string;
+}): string | null;
+/** Page on `explorer.leash.market` for an agent (MPL Core asset). */
+export declare function leashAgentUrl(mint: string | null | undefined, opts?: {
+    baseUrl?: string;
+}): string | null;
+//# sourceMappingURL=index.d.ts.map

package/dist/explorer/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/explorer/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,iBAAiB,CAAC;AAE7D,MAAM,MAAM,eAAe,GAAG;IAC5B,wEAAwE;IACxE,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,+BAA+B;IAC/B,QAAQ,CAAC,EAAE,gBAAgB,CAAC;CAC7B,CAAC;AAYF;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACpC,IAAI,GAAE,eAAoB,GACzB,MAAM,GAAG,IAAI,CAKf;AAED,8EAA8E;AAC9E,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAC/B,IAAI,GAAE,eAAoB,GACzB,MAAM,GAAG,IAAI,CAMf;AAED,yDAAyD;AACzD,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAClC,IAAI,GAAE,eAAoB,GACzB,MAAM,GAAG,IAAI,CAMf;AAED;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,kCAAkC,CAAC;AAEtE;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAC/B,IAAI,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAO,GAC9B,MAAM,GAAG,IAAI,CAMf;AAED,iEAAiE;AACjE,wBAAgB,UAAU,CACxB,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACpC,IAAI,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAO,GAC9B,MAAM,GAAG,IAAI,CAMf;AAED,qEAAqE;AACrE,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAC/B,IAAI,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAO,GAC9B,MAAM,GAAG,IAAI,CAMf"}

package/dist/explorer/index.js

@@ -0,0 +1,95 @@
+/**
+ * Explorer URL builders for Solana addresses, transactions, and Metaplex
+ * Core agent assets. Used by Leash to stamp `tx_explorer` /
+ * `agent_explorer` links into x402 response headers and to render "View on
+ * Solscan" affordances in the playground UI.
+ *
+ * We default to Solscan (best UX for SPL transfers and Core assets) but
+ * support `solana-explorer` (the official explorer.solana.com) as well.
+ */
+function clusterParam(network, provider) {
+    if (network === 'mainnet')
+        return '';
+    if (provider === 'solscan')
+        return '?cluster=devnet';
+    return '?cluster=devnet';
+}
+function base(provider) {
+    return provider === 'solscan' ? 'https://solscan.io' : 'https://explorer.solana.com';
+}
+/**
+ * Explorer page for an SPL token transfer / x402 settlement. Returns
+ * `null` when no signature is supplied so callers can pipe through `null`
+ * fields from receipts without nullish-checking inline.
+ */
+export function transactionExplorerUrl(signature, opts = {}) {
+    if (!signature)
+        return null;
+    const provider = opts.provider ?? 'solscan';
+    const network = opts.network ?? 'devnet';
+    return `${base(provider)}/tx/${signature}${clusterParam(network, provider)}`;
+}
+/** Explorer page for a Metaplex Core agent asset (the agent mint address). */
+export function agentExplorerUrl(mint, opts = {}) {
+    if (!mint)
+        return null;
+    // Core assets are addresses, so the address page gives the richest view
+    // (asset metadata + holder history). Solscan also accepts /token but
+    // /address surfaces the Core attributes plate.
+    return addressExplorerUrl(mint, opts);
+}
+/** Explorer page for any Solana account / mint / PDA. */
+export function addressExplorerUrl(address, opts = {}) {
+    if (!address)
+        return null;
+    const provider = opts.provider ?? 'solscan';
+    const network = opts.network ?? 'devnet';
+    const path = provider === 'solscan' ? 'account' : 'address';
+    return `${base(provider)}/${path}/${address}${clusterParam(network, provider)}`;
+}
+/**
+ * Default base for the Leash protocol explorer. Override via the
+ * `baseUrl` option (or `LEASH_EXPLORER_URL` upstream) when running
+ * against a self-hosted explorer or a staging deployment.
+ */
+export const LEASH_EXPLORER_DEFAULT = 'https://explorer.leash.market';
+/**
+ * Page on `explorer.leash.market` for a Leash receipt hash. Returns
+ * `null` when no hash is supplied so callers can pipe through nullable
+ * fields without inline checks.
+ *
+ * The hash should be the seller-side (canonical) `receipt_hash` — the
+ * one stamped on the response via `X-Leash-Receipt-Hash`. The
+ * buyer-kit's locally-computed hash is per-buyer-view and the explorer
+ * does not index it.
+ */
+export function leashReceiptUrl(hash, opts = {}) {
+    if (!hash)
+        return null;
+    const trimmed = hash.trim();
+    if (trimmed.length === 0)
+        return null;
+    const base = (opts.baseUrl ?? LEASH_EXPLORER_DEFAULT).replace(/\/+$/, '');
+    return `${base}/receipt/${encodeURIComponent(trimmed)}`;
+}
+/** Page on `explorer.leash.market` for a Solana tx signature. */
+export function leashTxUrl(signature, opts = {}) {
+    if (!signature)
+        return null;
+    const trimmed = signature.trim();
+    if (trimmed.length === 0)
+        return null;
+    const base = (opts.baseUrl ?? LEASH_EXPLORER_DEFAULT).replace(/\/+$/, '');
+    return `${base}/tx/${encodeURIComponent(trimmed)}`;
+}
+/** Page on `explorer.leash.market` for an agent (MPL Core asset). */
+export function leashAgentUrl(mint, opts = {}) {
+    if (!mint)
+        return null;
+    const trimmed = mint.trim();
+    if (trimmed.length === 0)
+        return null;
+    const base = (opts.baseUrl ?? LEASH_EXPLORER_DEFAULT).replace(/\/+$/, '');
+    return `${base}/agent/${encodeURIComponent(trimmed)}`;
+}
+//# sourceMappingURL=index.js.map

package/dist/explorer/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/explorer/index.ts"],"names":[],"mappings":"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"}

package/dist/fees/leash-fee.d.ts

@@ -0,0 +1,248 @@
+/**
+ * Leash protocol fee primitives.
+ *
+ * Every Leash-flavoured x402 settlement levies a small protocol fee on
+ * top of the seller's quoted price. The buyer signs **one** transaction
+ * with **two** `TransferChecked` instructions — one to the seller's
+ * `payTo` ATA, one to the Leash treasury's ATA on the same mint — so
+ * both legs settle atomically (either both transfers land or neither
+ * does). The fee leg is funded out of the same source token account as
+ * the seller leg.
+ *
+ * This module is the shared building block:
+ *   - {@link LEASH_FEE_BPS_DEFAULT} — 100 bps (1%) by default; overridable
+ *     by env at the seller (which advertises the fee in `extra['leash.fee']`)
+ *     and at the facilitator (which enforces it on `verify` / `settle`).
+ *   - {@link computeFeeAtoms} — `ceilBps(amount, bps)`. Always rounds the
+ *     fee **up** so dust never leaks out of the treasury when the buyer
+ *     pays a non-divisible price.
+ *   - {@link LeashFeeExtra} — wire shape stamped onto `paymentRequirements.extra`
+ *     so buyer + facilitator agree on bps, amount, mint authority, and ATA.
+ *   - {@link resolveLeashFeeAuthority} — env-driven lookup of the treasury
+ *     authority pubkey per network (mainnet / devnet).
+ *   - {@link getLeashFeeAtaFor} — derive the treasury's ATA for a given
+ *     `(asset, tokenProgram)` pair so seller + facilitator both end up
+ *     with the same destination address.
+ *
+ * Fee math is gross-up:
+ *   - Seller quotes `net` (e.g. 1 USDC = 1_000_000 atoms).
+ *   - Buyer pays `gross = net + fee` where `fee = ceil(net * bps / 10_000)`.
+ *   - At 100 bps: 1 USDC → buyer signs 1.01 USDC; 1.00 USDC lands in seller
+ *     ATA, 0.01 USDC lands in treasury ATA.
+ *
+ * Env vars (read at process boot — never inline a stale value):
+ *   - `LEASH_FEE_BPS`              — global default (integer 0..1000). Default 100.
+ *   - `LEASH_FEE_ENFORCE`          — `off | warn | enforce`. Default `warn`.
+ *   - `LEASH_FEE_ENFORCE_MAINNET`  — per-network override; falls back to LEASH_FEE_ENFORCE.
+ *   - `LEASH_FEE_ENFORCE_DEVNET`   — per-network override; falls back to LEASH_FEE_ENFORCE.
+ *   - `LEASH_FEE_AUTHORITY_MAINNET`— wallet pubkey that owns the mainnet fee ATAs.
+ *   - `LEASH_FEE_AUTHORITY_DEVNET` — wallet pubkey that owns the devnet  fee ATAs.
+ *
+ * Defaults bake in `3DdcJkvjW7KLtMeko3Zr57jEJWhqRHuPsEBFm1XJYh7W` on both
+ * clusters so a fresh deploy collects fees out of the box. Override via
+ * env to rotate the treasury without code changes.
+ */
+import { type Address } from '@solana/kit';
+import type { TokenNetwork } from '../tokens/index.js';
+/**
+ * Default protocol fee rate in basis points (1 bps = 0.01%). 100 bps = 1%.
+ * Used by both the seller-kit (when stamping `extra['leash.fee']`) and
+ * the facilitator (when verifying inbound payment payloads). Override
+ * per-network via the `LEASH_FEE_BPS` env var on both surfaces.
+ */
+export declare const LEASH_FEE_BPS_DEFAULT = 100;
+/**
+ * Default treasury authority on Solana mainnet. Owns the SPL token
+ * accounts (one ATA per stable mint) where Leash collects protocol fees.
+ * Set `LEASH_FEE_AUTHORITY_MAINNET` to override (e.g. when migrating to
+ * a multisig).
+ */
+export declare const LEASH_FEE_AUTHORITY_MAINNET_DEFAULT = "3DdcJkvjW7KLtMeko3Zr57jEJWhqRHuPsEBFm1XJYh7W";
+/**
+ * Default treasury authority on Solana devnet. Same key as mainnet by
+ * design — devnet uses a separate ATA per mint anyway, so reusing the
+ * authority just simplifies operational tooling. Override via
+ * `LEASH_FEE_AUTHORITY_DEVNET`.
+ */
+export declare const LEASH_FEE_AUTHORITY_DEVNET_DEFAULT = "3DdcJkvjW7KLtMeko3Zr57jEJWhqRHuPsEBFm1XJYh7W";
+/**
+ * Enforcement modes for the Leash protocol fee.
+ *
+ *   - `off`     — facilitator ignores fee logic entirely. Vanilla x402
+ *                 transactions verify exactly as before. Sellers that stamp
+ *                 a fee `extra` still get one through, but the facilitator
+ *                 will treat the second leg as an unknown instruction and
+ *                 reject it. Use only for tests / local dev.
+ *   - `warn`    — facilitator accepts both vanilla and fee-bearing payloads.
+ *                 If a fee payload is malformed (wrong amount, wrong dest,
+ *                 wrong authority), it logs and accepts. Use during the
+ *                 rollout window where third-party clients haven't shipped
+ *                 the upgrade yet.
+ *   - `enforce` — facilitator REJECTS any payload that doesn't carry a
+ *                 valid fee leg. The default once mainnet rollout is done.
+ *
+ * Default is `warn` so the upgrade lands without breaking older buyers.
+ */
+export type LeashFeeEnforcement = 'off' | 'warn' | 'enforce';
+/**
+ * Wire shape of the `paymentRequirements.extra['leash.fee']` block.
+ *
+ * Compact and sync-stampable: only the **static** fee parameters
+ * travel on the wire (`bps`, `feeAuthority`). The buyer + facilitator
+ * derive everything else (`feeAtomic`, `grossAtomic`, `feeDestination`)
+ * on demand from `(paymentRequirements.amount, asset, tokenProgram)`
+ * via {@link computeLeashFeeForRequirements} so all three surfaces
+ * agree byte-for-byte without any round-tripping.
+ *
+ * Sync stamping matters because seller-kit's `createSeller(...)` is
+ * a sync setup-time call; making it async would cascade through every
+ * downstream caller (web playground, demos, docs, tests).
+ */
+export type LeashFeeExtra = {
+    /**
+     * Discriminator. Always `'1'`. Bump when the wire shape changes so
+     * older facilitators reject incompatible payloads cleanly.
+     */
+    v: '1';
+    /**
+     * Fee rate in basis points the seller priced this `accepts[]` entry
+     * for (e.g. `100` for 1%). Sellers and facilitators must agree.
+     */
+    bps: number;
+    /**
+     * Treasury authority pubkey (the wallet that owns the destination
+     * fee ATA). Must match the env-configured authority on the
+     * facilitator side or verify will reject.
+     */
+    feeAuthority: string;
+};
+/**
+ * Compute the fee in atomic units for a given seller amount + bps,
+ * rounding **up** (`ceil`) so dust never leaks out of the treasury.
+ *
+ * Examples (bps=100):
+ *   - amount=1_000_000   → fee=10_000     (0.01 USDC for 1.00 USDC)
+ *   - amount=1           → fee=1          (1 atom for 1 atom — ceil)
+ *   - amount=999         → fee=10         (10 atoms for 999 atoms — ceil)
+ *
+ * @param amount seller leg amount in atomic units
+ * @param bps    integer 0..10_000
+ * @returns      atomic fee amount, never negative
+ */
+export declare function computeFeeAtoms(amount: bigint, bps: number): bigint;
+/**
+ * Convenience: given a `net` (seller's quoted) amount, return the
+ * `(net, fee, gross)` triple where `gross = net + fee` and
+ * `fee = ceilBps(net, bps)`.
+ *
+ * Use at seller-kit's `buildAccepts` time and on the buyer playground
+ * UI to render "you will pay X" disclosures.
+ */
+export declare function applyFeeGrossUp(netAmount: bigint, bps?: number): {
+    net: bigint;
+    fee: bigint;
+    gross: bigint;
+};
+/**
+ * Read the configured fee bps from env. Falls back to
+ * {@link LEASH_FEE_BPS_DEFAULT} when unset / unparseable. Validates
+ * the range so a bad env never surfaces as a 50_000 bps fee.
+ */
+export declare function resolveLeashFeeBps(): number;
+/**
+ * Read the configured fee authority for the given network from env.
+ * Falls back to the bundled defaults
+ * ({@link LEASH_FEE_AUTHORITY_MAINNET_DEFAULT} /
+ * {@link LEASH_FEE_AUTHORITY_DEVNET_DEFAULT}) when unset.
+ */
+export declare function resolveLeashFeeAuthority(network: TokenNetwork): string;
+/**
+ * Read the enforcement mode for the given network from env. Per-network
+ * vars override the global one. Default is `warn` everywhere so the
+ * rollout doesn't break older clients overnight.
+ */
+export declare function resolveLeashFeeEnforcement(network: TokenNetwork): LeashFeeEnforcement;
+/**
+ * Treasury ATA descriptor. `ata` is the on-chain associated token
+ * account address (where fees land); `authority` is the wallet that
+ * owns it (the fee-payer for any future treasury sweep).
+ */
+export type LeashFeeAccount = {
+    ata: Address;
+    authority: Address;
+};
+/**
+ * Derive the Leash fee ATA on the given `(network, asset, tokenProgram)`.
+ * Both the seller (when stamping `extra['leash.fee'].feeDestination`)
+ * and the facilitator (when verifying the second `TransferChecked`)
+ * call this so they always agree on the destination.
+ */
+export declare function getLeashFeeAtaFor(args: {
+    network: TokenNetwork;
+    /** SPL mint address the seller is collecting in. */
+    asset: string;
+    /**
+     * Token program owning the mint. Pass `'spl-token'` for legacy
+     * USDC/USDT and `'spl-token-2022'` for Token-2022 mints (USDG, etc.).
+     */
+    tokenProgram: 'spl-token' | 'spl-token-2022';
+    /** Optional override; defaults to {@link resolveLeashFeeAuthority}. */
+    authority?: string;
+}): Promise<LeashFeeAccount>;
+/**
+ * Build the static `extra['leash.fee']` payload for a given seller leg.
+ *
+ * Sync by construction: the wire shape only carries `bps` and
+ * `feeAuthority`, so seller-kit / payment-links can stamp this at
+ * `buildAccepts` time without making `createSeller` async. The buyer +
+ * facilitator derive the dynamic fields (`feeAtomic`, `grossAtomic`,
+ * `feeDestination`) on demand via {@link computeLeashFeeForRequirements}.
+ */
+export declare function buildLeashFeeExtra(args: {
+    network: TokenNetwork;
+    /** Defaults to {@link resolveLeashFeeBps}. */
+    bps?: number;
+    /** Defaults to {@link resolveLeashFeeAuthority}. */
+    authority?: string;
+}): LeashFeeExtra;
+/**
+ * Type guard + parser for an inbound `extra['leash.fee']` block. Returns
+ * `null` if the value is absent or malformed (any field missing /
+ * wrong type / out-of-range bps). Facilitators use this to decide whether
+ * to apply fee verification.
+ */
+export declare function parseLeashFeeExtra(extra: Record<string, unknown> | null | undefined): LeashFeeExtra | null;
+/**
+ * Resolved fee for a specific `paymentRequirements` entry. Buyer scheme
+ * + facilitator scheme both call {@link computeLeashFeeForRequirements}
+ * and then trust this exact triple, so they always agree.
+ */
+export type ResolvedLeashFee = {
+    bps: number;
+    feeAtomic: bigint;
+    grossAtomic: bigint;
+    feeAuthority: Address;
+    feeDestination: Address;
+};
+/**
+ * Resolve the per-request fee triple `(bps, feeAtomic, feeDestination)`
+ * for a given `paymentRequirements` entry. Returns `null` if the
+ * requirement carries no `extra['leash.fee']` (vanilla x402 mode).
+ *
+ * Both the buyer (when constructing the `TransferChecked` fee leg) and
+ * the facilitator (when verifying the inbound transaction) call this
+ * function so they always derive the same destination ATA + atomic
+ * amount from the same inputs.
+ */
+export declare function computeLeashFeeForRequirements(args: {
+    network: TokenNetwork;
+    /** SPL mint address (`paymentRequirements.asset`). */
+    asset: string;
+    /** Token program owning the mint. */
+    tokenProgram: 'spl-token' | 'spl-token-2022';
+    /** Seller leg amount in atomic units (`paymentRequirements.maxAmountRequired`). */
+    amount: string;
+    /** Parsed `extra['leash.fee']`. Pass `null` when absent. */
+    extra: LeashFeeExtra | null;
+}): Promise<ResolvedLeashFee | null>;
+//# sourceMappingURL=leash-fee.d.ts.map

package/dist/fees/leash-fee.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"leash-fee.d.ts","sourceRoot":"","sources":["../../src/fees/leash-fee.ts"],"names":[],"mappings":"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"}