@perkos/agent-sdk 0.1.0 → 0.2.0

package/dist/x402.d.ts

@@ -0,0 +1,60 @@
+import { decodePaymentRequiredHeader, decodePaymentResponseHeader, decodePaymentSignatureHeader, encodePaymentRequiredHeader, encodePaymentResponseHeader, encodePaymentSignatureHeader } from "@x402/core/http";
+import type { PaymentPayload, PaymentPayloadResult, PaymentRequired, PaymentRequirements, ResourceInfo, SchemeNetworkClient, SettleResponse } from "@x402/core/types";
+import type { AmountLike, ConfirmationOptions, ContractId, FundJobInput, JobRecord, PaymentAsset, PerkOSNetwork, ResolvedPerkOSConfig, TransactionConfirmation, TransactionReceipt } from "./types.js";
+export declare const X402_VERSION = 2;
+export declare const PERKOS_X402_SCHEME = "exact";
+export declare const PERKOS_X402_ASSET_TRANSFER_METHOD = "perkos-escrow-v1";
+export declare const PERKOS_X402_PAYMENT_FLOW = "upfront";
+export declare const STACKS_X402_NETWORKS: {
+    readonly mainnet: "stacks:1";
+    readonly testnet: "stacks:2147483648";
+};
+export interface PerkOSX402ClientLike {
+    readonly config: ResolvedPerkOSConfig;
+    getJob(asset: PaymentAsset, jobId: AmountLike): Promise<JobRecord | null>;
+    fundJob(input: FundJobInput): Promise<TransactionReceipt>;
+    confirm(receiptOrTxid: TransactionReceipt | string, options?: ConfirmationOptions): Promise<TransactionConfirmation>;
+}
+export interface PerkOSX402PaymentRequiredInput {
+    readonly resource: ResourceInfo;
+    readonly asset: PaymentAsset;
+    readonly jobId: AmountLike;
+    readonly amount: AmountLike;
+    readonly maxTimeoutSeconds?: number;
+    readonly error?: string;
+}
+export interface ParsedPerkOSX402Requirement {
+    readonly network: PerkOSNetwork;
+    readonly asset: PaymentAsset;
+    readonly jobId: bigint;
+    readonly amount: bigint;
+    readonly commerceContract: ContractId;
+    readonly assetIdentifier: string;
+    readonly maxTimeoutSeconds: number;
+}
+export interface PerkOSX402PaymentProof extends ParsedPerkOSX402Requirement {
+    readonly transaction: string;
+    readonly payer: string;
+    readonly blockHeight?: number;
+    readonly blockHash?: string;
+}
+export interface PerkOSX402SchemeClientOptions {
+    readonly client: PerkOSX402ClientLike;
+    readonly confirmation?: ConfirmationOptions;
+}
+export declare function toStacksX402Network(network: PerkOSNetwork): (typeof STACKS_X402_NETWORKS)[PerkOSNetwork];
+export declare function fromStacksX402Network(network: string): PerkOSNetwork;
+export declare function createPerkOSX402PaymentRequired(config: ResolvedPerkOSConfig, input: PerkOSX402PaymentRequiredInput): PaymentRequired;
+export declare function parsePerkOSX402Requirement(config: ResolvedPerkOSConfig, paymentRequirements: PaymentRequirements): ParsedPerkOSX402Requirement;
+export declare function parsePerkOSX402PaymentPayload(config: ResolvedPerkOSConfig, paymentPayload: PaymentPayload): PerkOSX402PaymentProof;
+export declare class PerkOSX402SchemeClient implements SchemeNetworkClient {
+    readonly scheme = "exact";
+    private readonly client;
+    private readonly confirmation;
+    constructor(options: PerkOSX402SchemeClientOptions);
+    createPaymentPayload(x402Version: number, paymentRequirements: PaymentRequirements): Promise<PaymentPayloadResult>;
+    private assertReceipt;
+}
+export { decodePaymentRequiredHeader, decodePaymentResponseHeader, decodePaymentSignatureHeader, encodePaymentRequiredHeader, encodePaymentResponseHeader, encodePaymentSignatureHeader, };
+export type { PaymentPayload, PaymentRequired, PaymentRequirements, ResourceInfo, SettleResponse, };
+//# sourceMappingURL=x402.d.ts.map

package/dist/x402.d.ts.map

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

package/dist/x402.js

@@ -0,0 +1,306 @@
+import { decodePaymentRequiredHeader, decodePaymentResponseHeader, decodePaymentSignatureHeader, encodePaymentRequiredHeader, encodePaymentResponseHeader, encodePaymentSignatureHeader, } from "@x402/core/http";
+import { validatePaymentPayload, validatePaymentRequired, validatePaymentRequirements, } from "@x402/core/schemas";
+import { PerkOSError } from "./errors.js";
+import { normalizeTxid } from "./txid.js";
+import { assertPrincipal, toUint } from "./validation.js";
+export const X402_VERSION = 2;
+export const PERKOS_X402_SCHEME = "exact";
+export const PERKOS_X402_ASSET_TRANSFER_METHOD = "perkos-escrow-v1";
+export const PERKOS_X402_PAYMENT_FLOW = "upfront";
+export const STACKS_X402_NETWORKS = {
+    mainnet: "stacks:1",
+    testnet: "stacks:2147483648",
+};
+const X402_NETWORK_TO_PERKOS = {
+    "stacks:1": "mainnet",
+    "stacks:2147483648": "testnet",
+};
+const DEFAULT_TIMEOUT_SECONDS = 600;
+const MAX_TIMEOUT_SECONDS = 3_600;
+function x402Error(message, details) {
+    return new PerkOSError("X402_INVALID", message, details);
+}
+function commerceContract(config, asset) {
+    return asset === "sbtc" ? config.contracts.sbtcCommerce : config.contracts.stxCommerce;
+}
+function assetIdentifier(config, asset) {
+    return asset === "sbtc"
+        ? `${config.contracts.sbtcToken}::${config.contracts.sbtcAssetName}`
+        : "STX";
+}
+function parseProtocolObject(label, parser) {
+    try {
+        return parser();
+    }
+    catch (cause) {
+        throw x402Error(`${label} is not a valid x402 v2 object.`, { cause });
+    }
+}
+function requireExtraString(extra, field) {
+    const value = extra[field];
+    if (typeof value !== "string" || value.length === 0) {
+        throw x402Error(`paymentRequirements.extra.${field} must be a non-empty string.`, {
+            field,
+            value,
+        });
+    }
+    return value;
+}
+function parseTimeout(value) {
+    if (!Number.isSafeInteger(value) || value <= 0 || value > MAX_TIMEOUT_SECONDS) {
+        throw x402Error(`maxTimeoutSeconds must be an integer between 1 and ${MAX_TIMEOUT_SECONDS}.`, { value });
+    }
+    return value;
+}
+function parseResource(resource) {
+    let url;
+    try {
+        url = new URL(resource.url);
+    }
+    catch (cause) {
+        throw x402Error("resource.url must be a valid HTTP or HTTPS URL.", { cause });
+    }
+    if (url.protocol !== "https:" && url.protocol !== "http:") {
+        throw x402Error("resource.url must use HTTP or HTTPS.", { protocol: url.protocol });
+    }
+    return resource;
+}
+export function toStacksX402Network(network) {
+    return STACKS_X402_NETWORKS[network];
+}
+export function fromStacksX402Network(network) {
+    const resolved = X402_NETWORK_TO_PERKOS[network];
+    if (!resolved) {
+        throw x402Error("network must be a supported Stacks CAIP-2 identifier.", { network });
+    }
+    return resolved;
+}
+export function createPerkOSX402PaymentRequired(config, input) {
+    const jobId = toUint(input.jobId, "jobId");
+    const amount = toUint(input.amount, "amount");
+    const contract = commerceContract(config, input.asset);
+    const timeout = parseTimeout(input.maxTimeoutSeconds ?? DEFAULT_TIMEOUT_SECONDS);
+    const paymentRequired = {
+        x402Version: X402_VERSION,
+        ...(input.error ? { error: input.error } : {}),
+        resource: parseResource(input.resource),
+        accepts: [
+            {
+                scheme: PERKOS_X402_SCHEME,
+                network: toStacksX402Network(config.network),
+                amount: amount.toString(),
+                asset: assetIdentifier(config, input.asset),
+                payTo: contract,
+                maxTimeoutSeconds: timeout,
+                extra: {
+                    assetTransferMethod: PERKOS_X402_ASSET_TRANSFER_METHOD,
+                    paymentFlow: PERKOS_X402_PAYMENT_FLOW,
+                    paymentAsset: input.asset,
+                    jobId: jobId.toString(),
+                    commerceContract: contract,
+                },
+            },
+        ],
+        extensions: {},
+    };
+    return parseProtocolObject("paymentRequired", () => {
+        validatePaymentRequired(paymentRequired);
+        return paymentRequired;
+    });
+}
+export function parsePerkOSX402Requirement(config, paymentRequirements) {
+    const requirements = parseProtocolObject("paymentRequirements", () => {
+        validatePaymentRequirements(paymentRequirements);
+        return paymentRequirements;
+    });
+    if (requirements.scheme !== PERKOS_X402_SCHEME) {
+        throw x402Error(`scheme must be ${PERKOS_X402_SCHEME}.`, {
+            scheme: requirements.scheme,
+        });
+    }
+    const network = fromStacksX402Network(requirements.network);
+    if (network !== config.network) {
+        throw x402Error("The x402 requirement network does not match the SDK client network.", {
+            requirementNetwork: network,
+            clientNetwork: config.network,
+        });
+    }
+    const extra = requirements.extra ?? {};
+    if (requireExtraString(extra, "assetTransferMethod") !== PERKOS_X402_ASSET_TRANSFER_METHOD) {
+        throw x402Error(`assetTransferMethod must be ${PERKOS_X402_ASSET_TRANSFER_METHOD}.`);
+    }
+    if (requireExtraString(extra, "paymentFlow") !== PERKOS_X402_PAYMENT_FLOW) {
+        throw x402Error(`paymentFlow must be ${PERKOS_X402_PAYMENT_FLOW}.`);
+    }
+    const paymentAsset = requireExtraString(extra, "paymentAsset");
+    if (paymentAsset !== "sbtc" && paymentAsset !== "stx") {
+        throw x402Error('paymentAsset must be "sbtc" or "stx".', { paymentAsset });
+    }
+    const asset = paymentAsset;
+    const expectedContract = commerceContract(config, asset);
+    const declaredContract = requireExtraString(extra, "commerceContract");
+    if (requirements.payTo !== expectedContract || declaredContract !== expectedContract) {
+        throw x402Error("payTo and commerceContract must match the configured escrow contract.", {
+            payTo: requirements.payTo,
+            declaredContract,
+            expectedContract,
+        });
+    }
+    const expectedAsset = assetIdentifier(config, asset);
+    if (requirements.asset !== expectedAsset) {
+        throw x402Error("The x402 asset does not match the configured settlement asset.", {
+            asset: requirements.asset,
+            expectedAsset,
+        });
+    }
+    const jobId = toUint(requireExtraString(extra, "jobId"), "jobId");
+    const amount = toUint(requirements.amount, "amount");
+    return {
+        network,
+        asset,
+        jobId,
+        amount,
+        commerceContract: expectedContract,
+        assetIdentifier: expectedAsset,
+        maxTimeoutSeconds: parseTimeout(requirements.maxTimeoutSeconds),
+    };
+}
+export function parsePerkOSX402PaymentPayload(config, paymentPayload) {
+    const parsed = parseProtocolObject("paymentPayload", () => {
+        validatePaymentPayload(paymentPayload);
+        return paymentPayload;
+    });
+    if (parsed.x402Version !== X402_VERSION) {
+        throw x402Error(`x402Version must be ${X402_VERSION}.`, {
+            x402Version: parsed.x402Version,
+        });
+    }
+    const requirement = parsePerkOSX402Requirement(config, parsed.accepted);
+    const transactionValue = parsed.payload.transaction;
+    const payer = parsed.payload.payer;
+    const jobId = parsed.payload.jobId;
+    const amount = parsed.payload.amount;
+    const paymentAsset = parsed.payload.asset;
+    const contract = parsed.payload.commerceContract;
+    if (typeof transactionValue !== "string") {
+        throw x402Error("payload.transaction must be a Stacks transaction ID.");
+    }
+    const transaction = normalizeTxid(transactionValue);
+    if (typeof payer !== "string") {
+        throw x402Error("payload.payer must be a Stacks principal.");
+    }
+    assertPrincipal(payer, "payload.payer", config.network);
+    if (jobId !== requirement.jobId.toString()) {
+        throw x402Error("payload.jobId does not match the accepted requirement.", {
+            jobId,
+            expectedJobId: requirement.jobId.toString(),
+        });
+    }
+    if (amount !== requirement.amount.toString()) {
+        throw x402Error("payload.amount does not match the accepted requirement.", {
+            amount,
+            expectedAmount: requirement.amount.toString(),
+        });
+    }
+    if (paymentAsset !== requirement.asset || contract !== requirement.commerceContract) {
+        throw x402Error("The payment proof asset or contract does not match the requirement.", {
+            paymentAsset,
+            contract,
+        });
+    }
+    const blockHeight = parsed.payload.blockHeight;
+    const blockHash = parsed.payload.blockHash;
+    if (blockHeight !== undefined &&
+        (typeof blockHeight !== "number" ||
+            !Number.isSafeInteger(blockHeight) ||
+            blockHeight < 0)) {
+        throw x402Error("payload.blockHeight must be a non-negative safe integer.");
+    }
+    if (blockHash !== undefined && typeof blockHash !== "string") {
+        throw x402Error("payload.blockHash must be a string.");
+    }
+    return {
+        ...requirement,
+        transaction,
+        payer,
+        ...(typeof blockHeight === "number" ? { blockHeight } : {}),
+        ...(typeof blockHash === "string" ? { blockHash } : {}),
+    };
+}
+export class PerkOSX402SchemeClient {
+    scheme = PERKOS_X402_SCHEME;
+    client;
+    confirmation;
+    constructor(options) {
+        this.client = options.client;
+        this.confirmation = options.confirmation ?? {};
+    }
+    async createPaymentPayload(x402Version, paymentRequirements) {
+        if (x402Version !== X402_VERSION) {
+            throw x402Error(`x402Version must be ${X402_VERSION}.`, { x402Version });
+        }
+        const requirement = parsePerkOSX402Requirement(this.client.config, paymentRequirements);
+        const job = await this.client.getJob(requirement.asset, requirement.jobId);
+        if (!job) {
+            throw x402Error(`Job ${requirement.jobId} does not exist.`, {
+                jobId: requirement.jobId,
+                asset: requirement.asset,
+            });
+        }
+        if (job.status !== "open") {
+            throw x402Error(`Job ${requirement.jobId} must be open before x402 funding.`, {
+                status: job.status,
+            });
+        }
+        if (job.budget !== requirement.amount) {
+            throw x402Error("The on-chain job budget does not match the x402 amount.", {
+                jobBudget: job.budget,
+                requirementAmount: requirement.amount,
+            });
+        }
+        const receipt = await this.client.fundJob({
+            asset: requirement.asset,
+            jobId: requirement.jobId,
+            amount: requirement.amount,
+            sender: job.client,
+        });
+        this.assertReceipt(receipt, requirement);
+        const confirmation = await this.client.confirm(receipt, this.confirmation);
+        if (confirmation.txid !== receipt.txid || confirmation.status !== "success") {
+            throw new PerkOSError("X402_PAYMENT_FAILED", "The Stacks escrow funding transaction did not confirm successfully.", {
+                receiptTxid: receipt.txid,
+                confirmationTxid: confirmation.txid,
+                status: confirmation.status,
+            });
+        }
+        return {
+            x402Version: X402_VERSION,
+            payload: {
+                transaction: receipt.txid,
+                payer: job.client,
+                jobId: requirement.jobId.toString(),
+                amount: requirement.amount.toString(),
+                asset: requirement.asset,
+                commerceContract: requirement.commerceContract,
+                ...(confirmation.blockHeight !== undefined
+                    ? { blockHeight: confirmation.blockHeight }
+                    : {}),
+                ...(confirmation.blockHash ? { blockHash: confirmation.blockHash } : {}),
+            },
+        };
+    }
+    assertReceipt(receipt, requirement) {
+        const valid = receipt.operation === "fund-job" &&
+            receipt.network === requirement.network &&
+            receipt.contract === requirement.commerceContract &&
+            receipt.asset === requirement.asset &&
+            receipt.amount === requirement.amount &&
+            receipt.jobId === requirement.jobId;
+        if (!valid) {
+            throw new PerkOSError("X402_PAYMENT_FAILED", "The SDK funding receipt does not match the accepted x402 requirement.", { receipt, requirement });
+        }
+        normalizeTxid(receipt.txid);
+    }
+}
+export { decodePaymentRequiredHeader, decodePaymentResponseHeader, decodePaymentSignatureHeader, encodePaymentRequiredHeader, encodePaymentResponseHeader, encodePaymentSignatureHeader, };
+//# sourceMappingURL=x402.js.map

package/dist/x402.js.map

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

package/docs/ARCHITECTURE.md

@@ -97,6 +97,29 @@ post-conditions:
 This difference stays inside the builder so frameworks do not duplicate asset-specific Clarity
 logic.
 
+## x402 v2 client adapter
+
+The x402 adapter uses the official v2 schemas and HTTP header codecs. It maps mainnet and testnet
+to their Stacks CAIP-2 identifiers and binds every payment requirement to the configured commerce
+contract, settlement asset, job ID, and exact atomic budget. `PerkOSX402SchemeClient` then reuses
+the normal read path, spending policy, signer, exact post-conditions, and confirmation tracker to
+produce a confirmed escrow-funding proof.
+
+`PerkOSX402Facilitator` closes the server-side observation boundary. It uses current Hiro v3
+transaction and event responses plus the Stacks chain tip, decodes the commerce contract's
+`job-funded` Clarity print event, matches the exact asset transfer, and atomically consumes the
+network-prefixed transaction ID through an injected replay store. The facilitator broadcasts no
+second transaction because the declared x402 payment flow is upfront.
+
+The included in-memory replay store is process-local and not production durability. A deployed
+resource server must inject shared atomic storage. The existing custom application headers are
+outside the SDK and are not implicitly treated as x402 v2.
+
+The confirmed funding transaction is public before its proof reaches the resource server. Replay
+consumption and a short freshness window do not cryptographically bind that bearer proof to one
+HTTP request, so a later request-bound signature/challenge or facilitator-submitted transaction is
+required before a high-value production paywall migration.
+
 ## Settlement safety
 
 Completion, rejection, and expiry may transfer funds held by the escrow contract rather than by
@@ -106,6 +129,7 @@ exact amount expected to leave it.
 
 ## Future adapters
 
-- x402 v2 resource-server and client adapters.
+- Durable replay-store and hosted HTTP adapters for the x402 Stacks facilitator.
+- Request-bound payer authorization for front-running resistance.
 - MCP tools with typed inputs, allowlists, and the same spending policy.
 - Optional framework-specific integrations and higher-confirmation settlement policies.

package/docs/plans/2026-08-25-stacks-x402-direct-profile-design.md

@@ -0,0 +1,68 @@
+# Nayori direct x402 Stacks profile
+
+Date: 2026-08-25
+Status: approved for implementation
+
+## Boundary
+
+This is an additive Milestone 2 SDK capability. It does not change the approved M1 contracts,
+broadcast transactions, host a facilitator, persist replay state, sponsor fees, or replace the
+existing `perkos-escrow-v1` job-funding mechanism. The direct mechanism is for an immediate paid
+resource; the existing mechanism remains for jobs with escrow, delivery, evaluation, payout, and
+reputation.
+
+## Decision
+
+Add a versioned `stacks-signed-tx-v1` mechanism for direct STX, sBTC, and USDCx payments using the
+official x402 v2 `exact` scheme and explicit `upfront` flow. The client signs the real Stacks
+transaction, and a later hosted facilitator validates and broadcasts it before the resource runs.
+
+The approved compatibility-first wire profile emits:
+
+- `STX` for native STX;
+- the canonical `address.contract` principal for sBTC and USDCx;
+- a full internal CAIP-19 identifier in `extra.nayoriAssetId` for every asset;
+- `extra.assetTransferMethod: "stacks-signed-tx-v1"`;
+- `extra.paymentFlow: "upfront"`.
+
+Unknown networks, assets, contracts, or token names fail closed. There is no fallback to STX.
+
+## Request binding
+
+A normalized trusted quote covers quote and merchant IDs, HTTP method, canonical absolute URL,
+SHA-256 body digest, network, canonical asset, exact atomic amount, recipient, issue time, and
+expiry. The canonical representation has fixed keys and version 1. Its SHA-256 digest is truncated
+to 20 bytes and encoded as `ny1_<base64url>`: 31 ASCII characters that fit both the 34-byte native
+STX memo and SIP-010 optional memo.
+
+The pure verifier receives the trusted quote and actual request, recomputes the fingerprint, and
+requires the signed transaction memo to match. The future hosted layer must authenticate the
+merchant and verify the quote signature before treating the quote as trusted.
+
+## Pure verifier
+
+The verifier has no network, database, replay, or broadcast side effects. It:
+
+1. validates the official x402 payload and requirement;
+2. requires payload `accepted` to equal the server requirement;
+3. matches requirement, trusted quote, and actual request;
+4. deserializes one canonical transaction with bounded size and no trailing bytes;
+5. verifies chain ID, transaction version, authorization type, and origin signature;
+6. derives the payer from the origin spending condition;
+7. permits only an exact STX token transfer or canonical SIP-010 `transfer` call;
+8. checks amount, sender, recipient, memo, contract, function, arguments, and asset;
+9. requires `PostConditionMode.Deny`; SIP-010 requires exactly one equal FT post-condition from
+   the payer for the canonical token and amount;
+10. returns a typed verified plan for a later settlement layer.
+
+Standard and origin-signed sponsored transactions are accepted. Sponsor signing, fee policy,
+nonce queues, balance checks, simulation, replay, idempotency, broadcast, confirmation, and
+delivery remain required hosted-service controls.
+
+## Testing
+
+Deterministic signed fixtures cover STX, sBTC, USDCx, mainnet/testnet registry values, canonical
+fingerprints, and sponsored origin signatures. Negative tests mutate the request, quote,
+requirement, network, signature, transaction template, recipient, amount, memo, contract,
+function arguments, post-condition mode, post-condition asset, and serialized bytes. No test calls
+a live RPC or broadcasts a transaction.

package/docs/plans/2026-08-25-stacks-x402-facilitator-design.md

@@ -0,0 +1,143 @@
+# Stacks x402 verifier and facilitator
+
+Date: 2026-08-25
+Status: approved for implementation by the M2 continuation
+
+## Milestone boundary
+
+Milestone 1 is approved and closed. This work is an additive `@perkos/agent-sdk` capability for
+Milestone 2 developer adoption and demo readiness. It does not change, redeploy, or charge a fee
+through the STX or sBTC contracts. It also does not replace the external security review or any
+mainnet/non-team adoption requirement.
+
+The deliverable is a reusable facilitator mechanism, not a hosted production service. It can be
+registered with the official `@x402/core` facilitator and can later power a Next.js route, a
+standalone facilitator, or an agent framework without duplicating Stacks verification logic.
+
+## Approaches considered
+
+### Deploy a hosted facilitator immediately
+
+This would create an immediately callable endpoint, but it also introduces hosting, rate limits,
+availability, durable storage, observability, and incident-response obligations before the core
+verification rules are reviewed. It is deferred.
+
+### Migrate the application middleware first
+
+The current application middleware uses custom `X-X402-*` headers and escrow-balance checks. A
+direct migration before independent transaction verification would make the surface look standard
+without closing its security boundary. It is deferred until the SDK mechanism is merged.
+
+### Add a reusable SDK facilitator with injected state
+
+This provides strict, testable verification and lets each host supply its own fetch implementation
+and atomic replay store. It aligns directly with the public SDK, example, and external-feedback
+parts of M2. This is the selected approach.
+
+## Protocol model
+
+The existing client uses `paymentFlow: "upfront"`: the buyer broadcasts and confirms `fund-job`
+before it asks for the protected resource again. Under the official x402 v2 flow table, upfront
+payments call facilitator settlement before the resource handler; read-only `/verify` is not part
+of the normal resource-server ordering. For this Stacks mechanism, settlement does not broadcast a
+second transaction. It independently observes the already confirmed escrow funding and atomically
+consumes its transaction ID as the one-time payment proof.
+
+The facilitator still implements `verify` because it is part of the standard facilitator API and
+is useful for diagnostics. `verify` never writes replay state. `settle` repeats verification and
+then performs the atomic replay-state transition before returning success.
+
+## Components
+
+`src/x402-facilitator.ts` will contain:
+
+1. `HiroX402TransactionSource`, a read-only client for current v3 transaction/event detail and
+   the chain tip.
+2. Strict parsers for the minimum Hiro response fields needed by the mechanism.
+3. Verification of requirement/payload equality, confirmation depth, freshness, payer, contract
+   call, function arguments, asset transfer event, amount, and client proof block metadata.
+4. `PerkOSX402Facilitator`, implementing the official `SchemeNetworkFacilitator` interface.
+5. `PerkOSX402ReplayStore`, an injected atomic-consume interface.
+6. `InMemoryX402ReplayStore`, safe for examples and one-process tests but explicitly unsuitable
+   for horizontally scaled production.
+
+The default transaction source uses the API URL already resolved by the SDK configuration. No API
+key, private key, signer, fee recipient, or treasury is needed.
+
+## Verification rules
+
+A payment is valid only when all checks pass:
+
+- The payload and supplied requirement are deeply equal and both pass the existing PerkOS x402
+  parser.
+- The transaction ID and claimed payer are valid for the configured Stacks network.
+- Hiro v3 returns a successful, indexed `contract_call` with an anchored block record.
+- The transaction sender equals the payload payer.
+- The contract and function are exactly the configured asset-specific commerce contract and
+  `fund-job`.
+- The decoded contract `job-funded` print event contains the exact job ID and amount. For sBTC, its
+  token principal is the configured canonical token.
+- A matching on-chain transfer event moves the exact requirement amount from the payer to the
+  commerce contract: canonical SIP-010 sBTC for sBTC, or micro-STX for STX.
+- The API block height/hash match any block metadata included in the client proof.
+- The transaction has the configured minimum confirmation count and is no older than the quote's
+  `maxTimeoutSeconds`, with a small configurable clock-skew allowance.
+- The network-prefixed transaction key has not already been consumed.
+
+The event check is mandatory even when a transaction result is `(ok true)`: successful execution
+alone does not prove that the quoted amount and asset moved into escrow.
+
+## Replay and concurrency
+
+The replay key is `${network}:${normalizedTxid}`. `settle` calls an atomic
+`consume(key, record): Promise<boolean>`. Exactly one concurrent caller can receive `true`; every
+later caller receives a replay failure. A production adapter must implement this with a unique
+database constraint or an atomic primitive such as Redis `SET NX`, and should retain records at
+least as long as any protected resource can be delivered.
+
+The in-memory implementation uses a process-local map and is only for tests, examples, local
+development, and a single-process demo. It must not be represented as durable or distributed
+replay protection.
+
+## Security limitation
+
+The current Stacks payload is proof of an already public transaction, not a private off-chain
+authorization bound cryptographically to an HTTP request. Confirmation freshness and first-writer
+replay consumption reduce stale reuse, but a party that obtains the proof before settlement could
+attempt to front-run it. The application must not migrate a high-value production paywall until a
+later design either gives the facilitator the signed transaction before broadcast or adds a
+request-bound payer signature/challenge.
+
+This limitation will be visible in the README and example. The mechanism is appropriate for M2
+integration evidence and controlled pilots, not an unaudited high-value production gateway.
+
+## Errors
+
+Malformed requirements, mismatches, failed transactions, insufficient confirmations, expired
+proofs, missing transfer events, and replay attempts return stable invalid-reason strings. Network
+or malformed API responses fail closed. Settlement never marks a proof consumed until every
+read-only verification check succeeds.
+
+If consumption succeeds, settlement returns the existing funding transaction, payer, Stacks
+CAIP-2 network, and exact atomic amount. It never claims to have broadcast another transaction.
+
+## Testing and evidence
+
+Unit tests will cover sBTC and STX success, official facilitator registration, malformed payloads,
+cross-network/requirement mismatch, wrong sender/contract/function/job/token/amount, missing or
+incorrect print/transfer events, failed or incomplete transaction evidence, insufficient
+confirmation, expiry, block metadata mismatch, API failure, and concurrent replay consumption.
+
+A wallet-free quickstart will inspect the public M1 mainnet sBTC funding transaction through Hiro
+and demonstrate that its contract call and transfer event match the expected escrow fields while
+the facilitator correctly refuses it as an expired x402 proof. It changes no M1 state and consumes
+no replay record. This is additional M2 SDK evidence, not a new M1 claim or adoption credit.
+
+## Follow-up
+
+1. Merge and publish the SDK verifier/facilitator.
+2. Obtain external technical feedback and include the module in the recorded M2 SDK demo.
+3. Add a durable replay-store adapter and thin hosted HTTP facilitator.
+4. Replace the application's custom x402 middleware only after the request-binding limitation has
+   an accepted mitigation.
+5. Continue the external security review and mainnet/non-team adoption work in parallel.