@unslept/sdk 0.0.0-stage → 0.1.0

package/dist/viem.js

@@ -0,0 +1,134 @@
+import { BaseError, ContractFunctionRevertedError, createPublicClient, createWalletClient, defineChain, http, parseEventLogs, } from "viem";
+import { agentAccountAbi, settlementRouterAbi, unsleptBufferAbi } from "./abi.js";
+import { UnsleptError } from "./errors.js";
+function need(name) {
+    const v = process.env[name]?.trim();
+    if (!v)
+        throw new UnsleptError("CONFIG", `${name} is not set. See .env.example for the Robinhood Chain settings.`);
+    return v;
+}
+/** Builds the chain client for the "robinhood-chain" preset from environment variables. Nothing is assumed. */
+export function createViemChainFromEnv(args) {
+    if (args.network !== "robinhood-chain") {
+        throw new UnsleptError("CONFIG", `Unknown network preset "${args.network}". Pass a chain implementation instead.`);
+    }
+    const id = Number(need("UNSLEPT_CHAIN_ID"));
+    const rpc = need("UNSLEPT_RPC_URL");
+    const chain = defineChain({
+        id,
+        name: process.env.UNSLEPT_CHAIN_NAME ?? "Robinhood Chain",
+        nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 },
+        rpcUrls: { default: { http: [rpc] } },
+    });
+    const account = args.signer;
+    if (!account || typeof account !== "object" || !("address" in account)) {
+        throw new UnsleptError("CONFIG", "signer must be a viem Account, for example privateKeyToAccount(key).");
+    }
+    const buffers = need("UNSLEPT_BUFFERS")
+        .split(",")
+        .map((s) => s.trim());
+    return createViemChain({
+        agentAccount: args.agentAccount,
+        usdg: need("UNSLEPT_USDG"),
+        router: need("UNSLEPT_ROUTER"),
+        buffers,
+        publicClient: createPublicClient({ chain, transport: http(rpc) }),
+        walletClient: createWalletClient({ chain, transport: http(rpc), account }),
+        account,
+        fromBlock: process.env.UNSLEPT_FROM_BLOCK ? BigInt(process.env.UNSLEPT_FROM_BLOCK) : undefined,
+    });
+}
+const revertMap = {
+    PerCallCapExceeded: (a) => new UnsleptError("PER_CALL_CAP", "Payment is above the per-call cap. Raise the cap in the spending policy.", { amount: a[0], cap: a[1] }),
+    DailyCapExceeded: (a) => new UnsleptError("DAILY_CAP", "Payment would pass today's cap. Wait for 00:00 UTC or raise the daily cap.", { spent: a[0], amount: a[1], cap: a[2] }),
+    PayeeNotAllowed: (a) => new UnsleptError("PAYEE_NOT_ALLOWED", `Payee ${String(a[0])} is not on the allowlist. Add it in the spending policy.`),
+    AgentPaused: () => new UnsleptError("AGENT_PAUSED", "This agent is paused. Its owner can resume it in the Unslept app."),
+    AgentRevoked: () => new UnsleptError("AGENT_REVOKED", "This agent was revoked. Create a new agent account."),
+    InsufficientCollateral: (a) => new UnsleptError("INSUFFICIENT_COLLATERAL", "The agent does not hold enough to cover this payment. Fund the agent account.", { debtAfter: a[0], value: a[1] }),
+    InsufficientBufferLiquidity: (a) => new UnsleptError("INSUFFICIENT_BUFFER_LIQUIDITY", "The buffer is short of liquidity right now. Retry shortly; it refills from parked positions.", { amount: a[0], available: a[1] }),
+};
+function mapRevert(err) {
+    if (err instanceof BaseError) {
+        const r = err.walk((e) => e instanceof ContractFunctionRevertedError);
+        if (r instanceof ContractFunctionRevertedError && r.data?.errorName) {
+            const f = revertMap[r.data.errorName];
+            if (f)
+                throw f(r.data.args ?? []);
+            throw new UnsleptError("SETTLEMENT_FAILED", `Settlement reverted with ${r.data.errorName}.`, { args: r.data.args });
+        }
+    }
+    throw new UnsleptError("SETTLEMENT_FAILED", `Settlement transaction failed: ${err.message}`);
+}
+export function createViemChain(cfg) {
+    const pc = cfg.publicClient;
+    const acct = { address: cfg.agentAccount, abi: agentAccountAbi };
+    const chainId = pc.chain?.id;
+    if (!chainId)
+        throw new UnsleptError("CONFIG", "The public client has no chain configured.");
+    return {
+        chainId,
+        usdg: cfg.usdg,
+        async isPayeeAllowed(payee, domain) {
+            return pc.readContract({ ...acct, functionName: "isPayeeAllowed", args: [payee, domain] });
+        },
+        async getAccountState() {
+            const [policy, remainingToday, paused, revoked, liquid, parked, debt] = await Promise.all([
+                pc.readContract({ ...acct, functionName: "policy" }),
+                pc.readContract({ ...acct, functionName: "remainingToday" }),
+                pc.readContract({ ...acct, functionName: "paused" }),
+                pc.readContract({ ...acct, functionName: "revoked" }),
+                pc.readContract({ ...acct, functionName: "liquid" }),
+                pc.readContract({ ...acct, functionName: "parkedValue" }),
+                Promise.all(cfg.buffers.map((b) => pc.readContract({ address: b, abi: unsleptBufferAbi, functionName: "debtOf", args: [cfg.agentAccount] }))).then((d) => d.reduce((x, y) => x + y, 0n)),
+            ]);
+            return { policy: { perCallCap: policy[0], dailyCap: policy[1] }, remainingToday, paused, revoked, liquid, parked, debt };
+        },
+        async requestPayment(input) {
+            try {
+                const { request } = await pc.simulateContract({
+                    ...acct,
+                    functionName: "requestPayment",
+                    args: [input],
+                    account: cfg.account,
+                });
+                const hash = await cfg.walletClient.writeContract(request);
+                const receipt = await pc.waitForTransactionReceipt({ hash });
+                if (receipt.status !== "success")
+                    throw new UnsleptError("SETTLEMENT_FAILED", `Transaction ${hash} reverted.`);
+                const [ev] = parseEventLogs({ abi: settlementRouterAbi, logs: receipt.logs, eventName: "Settled" });
+                if (!ev)
+                    throw new UnsleptError("SETTLEMENT_FAILED", `Transaction ${hash} has no Settled event.`);
+                return { transactionHash: hash, fee: ev.args.fee, buffer: ev.args.buffer };
+            }
+            catch (e) {
+                if (e instanceof UnsleptError)
+                    throw e;
+                mapRevert(e);
+            }
+        },
+        async setPolicy(policy) {
+            const { request } = await pc.simulateContract({ ...acct, functionName: "setPolicy", args: [policy], account: cfg.account });
+            return cfg.walletClient.writeContract(request);
+        },
+        async getPayments(opts) {
+            const logs = await pc.getContractEvents({
+                address: cfg.router,
+                abi: settlementRouterAbi,
+                eventName: "Settled",
+                args: { agent: cfg.agentAccount },
+                fromBlock: cfg.fromBlock ?? 0n,
+            });
+            const rows = logs.map((l) => ({
+                paymentId: l.args.paymentId,
+                payee: l.args.payee,
+                amount: l.args.amount,
+                fee: l.args.fee,
+                endpoint: l.args.endpoint,
+                transactionHash: l.transactionHash,
+                blockNumber: l.blockNumber,
+            }));
+            rows.reverse();
+            return opts?.limit ? rows.slice(0, opts.limit) : rows;
+        },
+    };
+}

package/dist/x402.d.ts

@@ -0,0 +1,112 @@
+/**
+ * x402 v2 HTTP transport types and helpers.
+ * Field names follow the x402 v2 specification (x402-foundation/x402, specs/x402-specification-v2.md)
+ * and the HTTP transport (specs/transports-v2/http.md): PAYMENT-REQUIRED, PAYMENT-SIGNATURE and
+ * PAYMENT-RESPONSE headers, each carrying base64-encoded JSON.
+ */
+export declare const X402_VERSION: 2;
+export declare const HEADER_REQUIRED = "PAYMENT-REQUIRED";
+export declare const HEADER_SIGNATURE = "PAYMENT-SIGNATURE";
+export declare const HEADER_RESPONSE = "PAYMENT-RESPONSE";
+/** Standard x402 scheme. Settled by a facilitator from an EIP-3009 authorization. */
+export declare const SCHEME_EXACT = "exact";
+/**
+ * Unslept scheme for merchants that opt in: the buffer pays `payTo` on-chain first and the client sends
+ * the transaction hash. The merchant (or its facilitator) verifies the SettlementRouter `Settled` event.
+ */
+export declare const SCHEME_UNSLEPT = "unslept-direct";
+export interface ResourceInfo {
+    url: string;
+    description?: string;
+    mimeType?: string;
+    serviceName?: string;
+    tags?: string[];
+    iconUrl?: string;
+}
+export interface PaymentRequirements {
+    scheme: string;
+    network: string;
+    amount: string;
+    asset: string;
+    payTo: string;
+    maxTimeoutSeconds: number;
+    extra?: Record<string, unknown>;
+}
+export interface PaymentRequired {
+    x402Version: number;
+    error?: string;
+    resource: ResourceInfo;
+    accepts: PaymentRequirements[];
+    extensions?: Record<string, unknown>;
+}
+export interface PaymentPayload<P = unknown> {
+    x402Version: number;
+    resource?: ResourceInfo;
+    accepted: PaymentRequirements;
+    payload: P;
+    extensions?: Record<string, unknown>;
+}
+export interface Eip3009Authorization {
+    from: string;
+    to: string;
+    value: string;
+    validAfter: string;
+    validBefore: string;
+    nonce: string;
+}
+export interface ExactEip3009Payload {
+    signature: string;
+    authorization: Eip3009Authorization;
+}
+export interface UnsleptDirectPayload {
+    transaction: string;
+    paymentId: string;
+    agentAccount: string;
+}
+export interface SettlementResponse {
+    success: boolean;
+    errorReason?: string;
+    payer?: string;
+    transaction: string;
+    network: string;
+}
+export declare const eip3009Types: {
+    readonly TransferWithAuthorization: readonly [{
+        readonly name: "from";
+        readonly type: "address";
+    }, {
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly name: "value";
+        readonly type: "uint256";
+    }, {
+        readonly name: "validAfter";
+        readonly type: "uint256";
+    }, {
+        readonly name: "validBefore";
+        readonly type: "uint256";
+    }, {
+        readonly name: "nonce";
+        readonly type: "bytes32";
+    }];
+};
+export declare function encodeHeader(value: unknown): string;
+export declare function decodeHeader<T>(value: string): T;
+export declare class X402FormatError extends Error {
+    readonly code = "X402_FORMAT";
+}
+/** Reads the PaymentRequired object from a 402 response. */
+export declare function readPaymentRequired(res: {
+    headers: {
+        get(name: string): string | null;
+    };
+}): PaymentRequired;
+export interface SelectOptions {
+    network: string;
+    asset: string;
+    schemes: string[];
+}
+/** Picks the first requirement matching our network and asset, by scheme preference. */
+export declare function selectRequirement(pr: PaymentRequired, opts: SelectOptions): PaymentRequirements | undefined;
+export declare function chainIdFromCaip2(network: string): number;

package/dist/x402.js

@@ -0,0 +1,82 @@
+/**
+ * x402 v2 HTTP transport types and helpers.
+ * Field names follow the x402 v2 specification (x402-foundation/x402, specs/x402-specification-v2.md)
+ * and the HTTP transport (specs/transports-v2/http.md): PAYMENT-REQUIRED, PAYMENT-SIGNATURE and
+ * PAYMENT-RESPONSE headers, each carrying base64-encoded JSON.
+ */
+export const X402_VERSION = 2;
+export const HEADER_REQUIRED = "PAYMENT-REQUIRED";
+export const HEADER_SIGNATURE = "PAYMENT-SIGNATURE";
+export const HEADER_RESPONSE = "PAYMENT-RESPONSE";
+/** Standard x402 scheme. Settled by a facilitator from an EIP-3009 authorization. */
+export const SCHEME_EXACT = "exact";
+/**
+ * Unslept scheme for merchants that opt in: the buffer pays `payTo` on-chain first and the client sends
+ * the transaction hash. The merchant (or its facilitator) verifies the SettlementRouter `Settled` event.
+ */
+export const SCHEME_UNSLEPT = "unslept-direct";
+export const eip3009Types = {
+    TransferWithAuthorization: [
+        { name: "from", type: "address" },
+        { name: "to", type: "address" },
+        { name: "value", type: "uint256" },
+        { name: "validAfter", type: "uint256" },
+        { name: "validBefore", type: "uint256" },
+        { name: "nonce", type: "bytes32" },
+    ],
+};
+function toBase64(s) {
+    let bin = "";
+    for (const byte of new TextEncoder().encode(s))
+        bin += String.fromCharCode(byte);
+    return btoa(bin);
+}
+function fromBase64(b64) {
+    return new TextDecoder().decode(Uint8Array.from(atob(b64), (c) => c.charCodeAt(0)));
+}
+export function encodeHeader(value) {
+    return toBase64(JSON.stringify(value));
+}
+export function decodeHeader(value) {
+    return JSON.parse(fromBase64(value.trim()));
+}
+export class X402FormatError extends Error {
+    code = "X402_FORMAT";
+}
+/** Reads the PaymentRequired object from a 402 response. */
+export function readPaymentRequired(res) {
+    const header = res.headers.get(HEADER_REQUIRED);
+    if (!header) {
+        throw new X402FormatError("The server answered 402 without a PAYMENT-REQUIRED header. Only x402 v2 servers are supported.");
+    }
+    let parsed;
+    try {
+        parsed = decodeHeader(header);
+    }
+    catch {
+        throw new X402FormatError("The PAYMENT-REQUIRED header is not valid base64-encoded JSON.");
+    }
+    if (parsed.x402Version !== X402_VERSION) {
+        throw new X402FormatError(`Unsupported x402Version ${parsed.x402Version}. Expected ${X402_VERSION}.`);
+    }
+    if (!Array.isArray(parsed.accepts) || parsed.accepts.length === 0) {
+        throw new X402FormatError("The PAYMENT-REQUIRED header lists no accepted payment methods.");
+    }
+    return parsed;
+}
+/** Picks the first requirement matching our network and asset, by scheme preference. */
+export function selectRequirement(pr, opts) {
+    const asset = opts.asset.toLowerCase();
+    for (const scheme of opts.schemes) {
+        const match = pr.accepts.find((r) => r.scheme === scheme && r.network === opts.network && r.asset.toLowerCase() === asset);
+        if (match)
+            return match;
+    }
+    return undefined;
+}
+export function chainIdFromCaip2(network) {
+    const m = /^eip155:(\d+)$/.exec(network);
+    if (!m)
+        throw new X402FormatError(`Network ${network} is not an EVM CAIP-2 identifier.`);
+    return Number(m[1]);
+}

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "@unslept/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Pay x402 paywalls from an Unslept agent account on Robinhood Chain.",
+  "type": "module",
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./viem": {
+      "types": "./dist/viem.d.ts",
+      "import": "./dist/viem.js"
+    }
+  },
+  "files": [
+    "LICENSE",
+    "README.md",
+    "dist"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node --import tsx --test test/*.test.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "peerDependencies": {
+    "viem": "^2.21.0"
+  },
+  "peerDependenciesMeta": {
+    "viem": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0",
+    "viem": "^2.21.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Unsleptxyz/Unslept.git",
+    "directory": "packages/sdk-ts"
+  },
+  "homepage": "https://unslept-o29g.vercel.app/docs"
+}