@altaga/x402-sui 1.0.1 → 1.0.2

package/README.MD

@@ -2,76 +2,7 @@
 
 > Modular [x402](https://www.x402.org/) implementation for **Sui Sponsored Transactions** (gas-station style).
 
-This package is a small, pluggable reference SDK for the x402 "Payment Required" HTTP
-pattern, targeting the **Sui** blockchain. The design separates concerns into three
-roles — **Client**, **Resource Server**, and **Facilitator** — and exposes an
-HTTP middleware layer so any Express-based API can gate routes behind a 402
-payment challenge with a few lines of glue.
-
-The bundled `sui/exact` scheme uses Sui's *sponsored transaction* model: the
-buyer signs the payment intent, the facilitator co-signs as the **gas owner**, and
-the resource server never touches a private key.
-
----
-
-## Table of Contents
-
-- [Architecture](#architecture)
-- [Installation](#installation)
-- [Project Layout](#project-layout)
-- [Protocol Flow](#protocol-flow)
-- [Quick Start](#quick-start)
-  - [1. Resource Server (the paid API)](#1-resource-server-the-paid-api)
-  - [2. Facilitator (the gas station)](#2-facilitator-the-gas-station)
-  - [3. Client (the buyer)](#3-client-the-buyer)
-- [Module Reference](#module-reference)
-  - [`core/client`](#coreclient)
-  - [`core/http`](#corehttp)
-  - [`core/server`](#coreserver)
-  - [`core/server-http`](#coreserver-http)
-  - [`core/facilitator`](#corefacilitator)
-  - [`sui/exact/client`](#suiexactclient)
-  - [`sui/exact/server`](#suiexactserver)
-  - [`sui/exact/facilitator`](#suiexactfacilitator)
-- [Building](#building)
-- [Peer Dependencies](#peer-dependencies)
-- [License](#license)
-
----
-
-## Architecture
-
-x402 is a request/response convention layered on top of HTTP 402 *Payment Required*:
-
-```
-┌─────────┐         ┌──────────────────┐         ┌──────────────┐
-│  Client │ ──GET──▶│  Resource Server │         │ Facilitator  │
-│         │         │  (Express route) │         │  (gas owner) │
-│         │◀─ 402 ──│                  │         │              │
-│         │  + x-accepts              │         │              │
-│         │  + x-facilitator-url      │         │              │
-│         │                           │         │              │
-│         │── POST /sponsor ────────────────────▶              │
-│         │◀── sponsored tx bytes ─────────────────            │
-│         │── GET + X-PAYMENT ──▶│                  │           │
-│         │                      │── /verify ──────▶│           │
-│         │                      │── /settle  ─────▶│           │
-│         │◀── 200 + x-payment-response ────────────│           │
-└─────────┘         └──────────────────┘         └──────────────┘
-```
-
-The SDK mirrors that split into three independent core modules, each of which
-is scheme-agnostic. Scheme implementations (currently just `sui/exact`) are
-plugged in with a simple `register(schemeName:network, impl)` call — wildcards
-(`sui:*`, `*:*`) are supported.
-
-| Role | Module | Responsibility |
-|------|--------|----------------|
-| Client | `core/client`, `core/http` | Parse a 402 challenge, pick a supported scheme, ask the facilitator to sponsor, sign the tx, replay the request with `X-PAYMENT`. |
-| Resource Server | `core/server`, `core/server-http` | Issue 402 challenges for protected routes; verify and settle payments via the facilitator. |
-| Facilitator | `core/facilitator` | Co-sign transactions as gas owner, dry-run to verify, and submit to the chain. |
-
----
+This package provides an SDK for the x402 "Payment Required" HTTP pattern, targeting the **Sui** blockchain. The bundled `sui/exact` scheme uses Sui's *sponsored transaction* model: the buyer signs the payment intent, the facilitator co-signs as the gas owner, and the resource server never touches a private key.
 
 ## Installation
 
@@ -85,77 +16,6 @@ You also need the peer dependencies in your project:
 npm install @mysten/sui @mysten/bcs express
 ```
 
-> Pre-built bundles live in [`dist/`](./dist). The build step is only required
-> if you're modifying the source under `core/` or `sui/`.
-
----
-
-## Project Layout
-
-```
-sdk/
-├── core/                       # Scheme-agnostic framework
-│   ├── client.mjs              # x402Client — scheme registry & lookup
-│   ├── http.mjs                # x402HTTPClient — parse 402, encode X-PAYMENT
-│   ├── server.mjs              # x402ResourceServer — verify+settle via facilitator
-│   ├── server-http.mjs         # x402HTTPResourceServer — Express middleware
-│   └── facilitator.mjs         # x402Facilitator — sponsor / verify / settle
-├── sui/
-│   └── exact/                  # The "exact" payment scheme on Sui
-│       ├── client.mjs          # Builds the payment PTB, signs, asks for sponsor
-│       ├── server.mjs          # Passthrough (work happens in facilitator)
-│       └── facilitator.mjs     # Co-signs as gas owner, dry-runs, submits
-├── dist/                       # esbuild output (consumed via package exports)
-├── package.json
-└── README.MD
-```
-
-`package.json` exposes each piece as a subpath export so consumers can import
-only what they need:
-
-```json
-{
-  "@altaga/x402-sui/core/client":          "…",
-  "@altaga/x402-sui/core/http":            "…",
-  "@altaga/x402-sui/core/server":          "…",
-  "@altaga/x402-sui/core/server-http":     "…",
-  "@altaga/x402-sui/core/facilitator":     "…",
-  "@altaga/x402-sui/sui/exact/client":     "…",
-  "@altaga/x402-sui/sui/exact/server":     "…",
-  "@altaga/x402-sui/sui/exact/facilitator":"…"
-}
-```
-
----
-
-## Protocol Flow
-
-1. **Challenge.** The client requests a protected route. The server replies
-   `402 Payment Required` with:
-   - `X-Accepts`: base64-encoded JSON array of accepted `{ scheme, network, asset, payTo, maxAmountRequired, ... }` payment requirements.
-   - `X-Facilitator-Url`: where the client should ask for gas sponsorship.
-
-2. **Sponsor.** The client picks a supported scheme from `X-Accepts`, builds
-   the payment transaction (a `splitCoins` + `transferObjects` PTB on Sui),
-   and POSTs the raw tx bytes + sender address to `{facilitatorUrl}/sponsor`.
-   The facilitator returns `sponsoredTxBytes` (with itself as `gasOwner`) and
-   its `sponsorSignature`.
-
-3. **Sign.** The client signs the sponsored bytes with its own keypair.
-
-4. **Pay.** The client replays the original request with `X-PAYMENT:`
-   (base64 JSON of `{ scheme, network, transaction, signature, amount, payTo, asset }`).
-
-5. **Verify & Settle.** The server forwards the payload to the facilitator:
-   - `/verify` performs a `dryRunTransactionBlock` to mathematically prove the
-     tx would succeed.
-   - `/settle` calls `executeTransactionBlock` with the combined
-     `[buyerSignature, sponsorSignature]` array and returns the digest.
-
-6. **Respond.** On success, the server attaches `X-Payment-Response` (base64
-   JSON containing the `transactionDigest`) and hands off to the actual route
-   handler.
-
 ---
 
 ## Quick Start
@@ -164,23 +24,23 @@ only what they need:
 
 ```js
 import express from "express";
-import { SuiClient } from "@mysten/sui/client";
-
-import { x402ResourceServer } from "@altaga/x402-sui/core/server";
-import { HTTPFacilitatorClient } from "@altaga/x402-sui/core/http";
-import { x402HTTPResourceServer } from "@altaga/x402-sui/core/server-http";
-import { ExactSuiServerScheme } from "@altaga/x402-sui/sui/exact/server";
+import { 
+  x402ResourceServer, 
+  HTTPFacilitatorClient, 
+  x402HTTPResourceServer, 
+  ExactSuiServerScheme 
+} from "@altaga/x402-sui";
 
 const app = express();
 
-// 1. The server is configured with the URL of a trusted facilitator
+// The server is configured with the URL of a trusted facilitator
 const facilitator = new HTTPFacilitatorClient({ url: "https://facilitator.example.com" });
 const resourceServer = new x402ResourceServer(facilitator);
 
-// 2. Register scheme(s) you want to accept. Wildcards ("sui:*", "*:*") are OK.
+// Register scheme(s) you want to accept. Wildcards ("sui:*", "*:*") are OK.
 resourceServer.register("exact:sui:mainnet", new ExactSuiServerScheme());
 
-// 3. Declare which routes are paid, and what they cost
+// Declare which routes are paid, and what they cost
 const routes = {
   "GET /premium": {
     accepts: {
@@ -196,7 +56,7 @@ const routes = {
 
 app.use(new x402HTTPResourceServer(resourceServer, routes).middleware());
 
-// 4. The actual handler — req.payment is populated by the middleware
+// The actual handler — req.payment is populated by the middleware
 app.get("/premium", (req, res) => {
   res.json({ ok: true, paid: req.payment });
 });
@@ -210,9 +70,7 @@ app.listen(3000);
 import express from "express";
 import { SuiClient } from "@mysten/sui/client";
 import { Ed25519Keypair } from "@mysten/sui/keypairs/ed25519";
-
-import { x402Facilitator } from "@altaga/x402-sui/core/facilitator";
-import { ExactSuiFacilitatorScheme } from "@altaga/x402-sui/sui/exact/facilitator";
+import { x402Facilitator, ExactSuiFacilitatorScheme } from "@altaga/x402-sui";
 
 const client = new SuiClient({ url: "https://fullnode.mainnet.sui.io" });
 const keypair = Ed25519Keypair.fromSecretKey(process.env.FACILITATOR_SECRET);
@@ -256,21 +114,15 @@ app.post("/settle", async (req, res) => {
   }
 });
 
-app.listen: 4000;
+app.listen(4000);
 ```
 
-> The facilitator keypair must hold SUI for gas. If `client.getCoins` returns
-> zero gas coins, sponsorship fails with `Facilitator out of gas!`.
-
 ### 3. Client (the buyer)
 
 ```js
 import { SuiClient } from "@mysten/sui/client";
 import { Ed25519Keypair } from "@mysten/sui/keypairs/ed25519";
-
-import { x402Client } from "@altaga/x402-sui/core/client";
-import { x402HTTPClient } from "@altaga/x402-sui/core/http";
-import { ExactSuiClientScheme } from "@altaga/x402-sui/sui/exact/client";
+import { x402Client, x402HTTPClient, ExactSuiClientScheme } from "@altaga/x402-sui";
 
 const sui = new SuiClient({ url: "https://fullnode.mainnet.sui.io" });
 const keypair = Ed25519Keypair.fromSecretKey(process.env.BUYER_SECRET);
@@ -304,136 +156,86 @@ console.log("data:", await res.json(), "settle:", settleInfo);
 
 ---
 
-## Module Reference
+## API Reference
 
-### `core/client`
+### Client Setup (`x402Client` & `x402HTTPClient`)
 
-`x402Client` — a tiny scheme registry. `register(pattern, impl)` accepts
-`scheme:network`, `scheme:*`, or `*:*`; `getScheme(scheme, network)` resolves
-with the most specific match. Throws if nothing is registered.
-
-### `core/http`
-
-`x402HTTPClient(coreClient)` — HTTP-specific glue on top of a core client:
-
-- `getPaymentRequiredResponse(getHeaderFn, bodyJson)` — decodes `X-Accepts`
-  (base64 JSON) and reads `X-Facilitator-Url` (with body fallback).
-- `createPaymentPayload(paymentRequired)` — iterates `accepts`, hands the
-  first one a registered scheme can fulfil, and returns a normalized
-  `{ scheme, network, transaction, signature, amount, payTo, asset }`.
-- `encodePaymentSignatureHeader(payload)` — base64-encodes the payload for
-  the `X-PAYMENT` request header.
-- `getPaymentSettleResponse(getHeaderFn)` — decodes `X-Payment-Response` if
-  present.
-
-### `core/server`
-
-`x402ResourceServer(facilitatorClient)` — the server-side brain.
-
-- `register(pattern, impl)` — same lookup rules as the client.
-- `initialize()` — async hook for parity with richer implementations.
-- `handlePayment(paymentPayload, routes)` — calls
-  `facilitatorClient.verify(...)` then `facilitatorClient.settle(...)` and
-  returns the settlement result.
-
-`HTTPFacilitatorClient({ url })` — the default transport, POSTing JSON to
-`{url}/verify` and `{url}/settle`. Roll your own if you need mTLS or auth
-headers.
-
-### `core/server-http`
-
-`x402HTTPResourceServer(resourceServer, routesConfig).middleware()` returns
-an Express middleware that:
+```js
+import { x402Client, x402HTTPClient } from "@altaga/x402-sui";
 
-1. Looks up the route via `${req.method} ${req.path}`.
-2. If no `X-PAYMENT` header is present, responds `402` with
-   `X-Accepts` + `X-Facilitator-Url`.
-3. If a header is present, base64-decodes it, calls
-   `resourceServer.handlePayment(...)`, attaches `X-Payment-Response` to the
-   outgoing response, populates `req.payment`, and calls `next()`.
-4. On error, responds `400` with the error message.
+const core = new x402Client();
+core.register("exact:sui:mainnet", schemeImpl);   // exact match
+core.register("exact:sui:*",        wildcardImpl); // any network
+core.register("*:*",                catchAllImpl); // any scheme/network
 
-### `core/facilitator`
+const http = new x402HTTPClient(core);
 
-`x402Facilitator` — scheme registry + dispatch for the three facilitator
-operations:
+// Decode a 402 response
+const paymentRequired = http.getPaymentRequiredResponse(
+  (name) => res.headers.get(name),
+  null
+);
 
-- `sponsor(schemeName, network, payload)` — typically turns a raw client PTB
-  into a sponsored transaction with the facilitator as `gasOwner`.
-- `verify(paymentPayload, paymentRequirements)` — must return
-  `{ isValid: true }` or throw.
-- `settle(paymentPayload, paymentRequirements)` — must return
-  `{ transactionDigest }` or throw.
+// Build + sign + sponsor the payment
+const payload = await http.createPaymentPayload(paymentRequired);
 
-### `sui/exact/client`
+// Read the settlement info from the final response
+const settleInfo = http.getPaymentSettleResponse((n) => res.headers.get(n));
+```
 
-`ExactSuiClientScheme(client, keypair)` — implements `createPaymentPayload`:
+### Server Setup (`x402ResourceServer` & `x402HTTPResourceServer`)
 
-1. Fetchs the buyer's coins of `requirement.asset`; aborts if none exist.
-2. Builds a PTB: `splitCoins(coin, [amount])` → `transferObjects([split], payTo)`.
-3. If a `facilitatorUrl` was advertised, POSTs the raw bytes to
-   `{facilitatorUrl}/sponsor` and receives `sponsoredTxBytes` +
-   `sponsorSignature`.
-4. Signs the (possibly sponsored) bytes with the buyer's keypair and returns
-   `{ transaction, signature: [buyer, sponsor?] }`.
+```js
+import express from "express";
+import { x402ResourceServer, HTTPFacilitatorClient, x402HTTPResourceServer } from "@altaga/x402-sui";
 
-### `sui/exact/server`
+const app = express();
 
-`ExactSuiServerScheme` — intentionally empty. On Sui, the heavy lifting
-(verification, gas sponsorship, submission) is done by the facilitator, so
-the server-side scheme is a passthrough. Register one for parity:
+const facilitator = new HTTPFacilitatorClient({ url: "https://facilitator.example.com" });
+const resourceServer = new x402ResourceServer(facilitator);
 
-```js
 resourceServer.register("exact:sui:mainnet", new ExactSuiServerScheme());
-```
+await resourceServer.initialize();
 
-### `sui/exact/facilitator`
+const routes = {
+  "GET /premium": { accepts: { /* ... */ } },
+  "POST /upload": { accepts: { /* ... */ } },
+};
 
-`ExactSuiFacilitatorScheme(client, keypair)` — the gas station.
+app.use(new x402HTTPResourceServer(resourceServer, routes).middleware());
+```
 
-- **`sponsor({ txBytes, sender })`** — deserializes the buyer's PTB, overrides
-  `setSender(sender)`, `setGasOwner(self)`, picks a gas coin, sets a
-  `setGasBudget(10_000_000)` and `setGasPrice(1000)`, calls `tx.build`, and
-  returns `{ sponsoredTxBytes, sponsorSignature }`.
-- **`verify(payload, reqs)`** — `dryRunTransactionBlock` on the decoded
-  bytes; succeeds only if `effects.status.status === "success"`.
-- **`settle(payload, reqs)`** — `executeTransactionBlock` with the combined
-  signature array; returns `{ transactionDigest }` on success.
+### Facilitator Setup (`x402Facilitator`)
 
----
+```js
+import { x402Facilitator } from "@altaga/x402-sui";
 
-## Building
+const facilitator = new x402Facilitator();
+facilitator.register("exact:sui:mainnet", new ExactSuiFacilitatorScheme(sui, keypair));
 
-Source modules are written as `.mjs`. To rebuild the `dist/` bundles:
+// Sponsor — turn a raw client PTB into a gas-sponsored transaction
+const { sponsoredTxBytes, sponsorSignature } = await facilitator.sponsor("exact", "sui:mainnet", { txBytes, sender });
 
-```bash
-npm run build
-```
-
-Which is shorthand for:
+// Verify — must return { isValid: true } or throw
+const verify = await facilitator.verify(paymentPayload, paymentRequirements);
 
-```bash
-esbuild core/*.mjs sui/exact/*.mjs \
-  --outdir=dist \
-  --minify \
-  --format=esm \
-  --target=es2022
+// Settle — must return { transactionDigest } or throw
+const { transactionDigest } = await facilitator.settle(paymentPayload, paymentRequirements);
 ```
 
----
-
-## Peer Dependencies
+### Sui Exact Scheme
 
-| Package | Version | Why |
-|---------|---------|-----|
-| [`@mysten/sui`](https://www.npmjs.com/package/@mysten/sui) | `^1.14.0` | `Transaction`, `SuiClient`, keypairs |
-| [`@mysten/bcs`](https://www.npmjs.com/package/@mysten/bcs) | `^1.2.0`  | `toBase64` for serializing built PTBs |
-| [`express`](https://www.npmjs.com/package/express) | `^4.21.2` | Used by `x402HTTPResourceServer.middleware()` |
+Provides the native implementations for the `exact` payment scheme on Sui:
 
-`esbuild` is only needed if you re-run the build.
+```js
+import { ExactSuiClientScheme, ExactSuiServerScheme, ExactSuiFacilitatorScheme } from "@altaga/x402-sui";
 
----
+// Buyer
+core.register("exact:sui:mainnet", new ExactSuiClientScheme(sui, buyerKeypair));
 
-## License
+// Server
+resourceServer.register("exact:sui:mainnet", new ExactSuiServerScheme());
 
-[MIT](./LICENSE) — © Altaga
+// Facilitator
+facilitator.register("exact:sui:mainnet", new ExactSuiFacilitatorScheme(sui, sponsorKeypair));
+```

package/dist/index.js

@@ -0,0 +1 @@
+export*from"./core/client.mjs";export*from"./core/http.mjs";export*from"./core/facilitator.mjs";export*from"./core/server.mjs";export*from"./core/server-http.mjs";export*from"./sui/exact/client.mjs";export*from"./sui/exact/server.mjs";export*from"./sui/exact/facilitator.mjs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@altaga/x402-sui",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Modular x402 implementation for Sui Sponsored Transactions",
   "main": "dist/core/client.js",
   "type": "module",
@@ -11,10 +11,11 @@
     "dist"
   ],
   "scripts": {
-    "build": "esbuild core/*.mjs sui/exact/*.mjs --outdir=dist --minify --format=esm --target=es2022",
+    "build": "esbuild index.mjs core/*.mjs sui/exact/*.mjs --outdir=dist --minify --format=esm --target=es2022",
     "test": "echo \"Error: no test specified\" && exit 1"
   },
   "exports": {
+    ".": "./dist/index.js",
     "./core/client": "./dist/core/client.js",
     "./core/http": "./dist/core/http.js",
     "./core/server": "./dist/core/server.js",