@absol-labs/agent 0.11.0 → 0.12.0-rc.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +43 -51
- package/dist/capability/invocation-capability.d.ts +2 -2
- package/dist/capability/probe-capability.d.ts +225 -0
- package/dist/capability/probe-capability.d.ts.map +1 -0
- package/dist/capability/probe-capability.js +248 -0
- package/dist/capability/probe-capability.js.map +1 -0
- package/dist/cli/args.d.ts +11 -0
- package/dist/cli/args.d.ts.map +1 -1
- package/dist/cli/args.js +23 -0
- package/dist/cli/args.js.map +1 -1
- package/dist/cli/commands/claim.d.ts +32 -0
- package/dist/cli/commands/claim.d.ts.map +1 -1
- package/dist/cli/commands/claim.js +116 -28
- package/dist/cli/commands/claim.js.map +1 -1
- package/dist/cli/commands/close.d.ts.map +1 -1
- package/dist/cli/commands/close.js +35 -3
- package/dist/cli/commands/close.js.map +1 -1
- package/dist/cli/commands/invoke.d.ts +2 -0
- package/dist/cli/commands/invoke.d.ts.map +1 -1
- package/dist/cli/commands/invoke.js +2 -2
- package/dist/cli/commands/invoke.js.map +1 -1
- package/dist/cli/commands/mcp.d.ts.map +1 -1
- package/dist/cli/commands/mcp.js +15 -2
- package/dist/cli/commands/mcp.js.map +1 -1
- package/dist/cli/commands/open.d.ts.map +1 -1
- package/dist/cli/commands/open.js +58 -4
- package/dist/cli/commands/open.js.map +1 -1
- package/dist/cli/commands/pay.d.ts +34 -0
- package/dist/cli/commands/pay.d.ts.map +1 -0
- package/dist/cli/commands/pay.js +479 -0
- package/dist/cli/commands/pay.js.map +1 -0
- package/dist/cli/commands/reclaim-unverified.d.ts.map +1 -1
- package/dist/cli/commands/reclaim-unverified.js +3 -2
- package/dist/cli/commands/reclaim-unverified.js.map +1 -1
- package/dist/cli/commands/reclaim.d.ts +23 -2
- package/dist/cli/commands/reclaim.d.ts.map +1 -1
- package/dist/cli/commands/reclaim.js +204 -20
- package/dist/cli/commands/reclaim.js.map +1 -1
- package/dist/cli/commands/refund.d.ts +31 -0
- package/dist/cli/commands/refund.d.ts.map +1 -0
- package/dist/cli/commands/refund.js +397 -0
- package/dist/cli/commands/refund.js.map +1 -0
- package/dist/cli/commands/status.d.ts.map +1 -1
- package/dist/cli/commands/status.js +21 -2
- package/dist/cli/commands/status.js.map +1 -1
- package/dist/cli/commands/streams.js +8 -12
- package/dist/cli/commands/streams.js.map +1 -1
- package/dist/cli/commands/watch.d.ts.map +1 -1
- package/dist/cli/commands/watch.js +4 -1
- package/dist/cli/commands/watch.js.map +1 -1
- package/dist/cli/config.d.ts +44 -26
- package/dist/cli/config.d.ts.map +1 -1
- package/dist/cli/config.js +88 -38
- package/dist/cli/config.js.map +1 -1
- package/dist/cli/context.d.ts +19 -0
- package/dist/cli/context.d.ts.map +1 -1
- package/dist/cli/deps.d.ts +53 -0
- package/dist/cli/deps.d.ts.map +1 -1
- package/dist/cli/deps.js +51 -1
- package/dist/cli/deps.js.map +1 -1
- package/dist/cli/errors.d.ts.map +1 -1
- package/dist/cli/errors.js +21 -1
- package/dist/cli/errors.js.map +1 -1
- package/dist/cli/escape-hatch.d.ts +6 -4
- package/dist/cli/escape-hatch.d.ts.map +1 -1
- package/dist/cli/escape-hatch.js +6 -2
- package/dist/cli/escape-hatch.js.map +1 -1
- package/dist/cli/listings.d.ts +18 -0
- package/dist/cli/listings.d.ts.map +1 -1
- package/dist/cli/listings.js +22 -12
- package/dist/cli/listings.js.map +1 -1
- package/dist/cli/preflight.d.ts +20 -14
- package/dist/cli/preflight.d.ts.map +1 -1
- package/dist/cli/preflight.js +34 -20
- package/dist/cli/preflight.js.map +1 -1
- package/dist/cli/privy.d.ts.map +1 -1
- package/dist/cli/privy.js +4 -2
- package/dist/cli/privy.js.map +1 -1
- package/dist/cli/progress.d.ts +13 -1
- package/dist/cli/progress.d.ts.map +1 -1
- package/dist/cli/progress.js +7 -1
- package/dist/cli/progress.js.map +1 -1
- package/dist/cli/reclaimability.d.ts +82 -0
- package/dist/cli/reclaimability.d.ts.map +1 -0
- package/dist/cli/reclaimability.js +80 -0
- package/dist/cli/reclaimability.js.map +1 -0
- package/dist/cli/run.d.ts +2 -1
- package/dist/cli/run.d.ts.map +1 -1
- package/dist/cli/run.js +62 -21
- package/dist/cli/run.js.map +1 -1
- package/dist/cli/scan-range.d.ts +2 -2
- package/dist/cli/scan-range.js +2 -2
- package/dist/cli/status.d.ts +106 -1
- package/dist/cli/status.d.ts.map +1 -1
- package/dist/cli/status.js +325 -44
- package/dist/cli/status.js.map +1 -1
- package/dist/cli/wallet.d.ts +2 -2
- package/dist/cli/wallet.d.ts.map +1 -1
- package/dist/cli/wallet.js +29 -5
- package/dist/cli/wallet.js.map +1 -1
- package/dist/discovery/rate-band.d.ts +74 -0
- package/dist/discovery/rate-band.d.ts.map +1 -0
- package/dist/discovery/rate-band.js +114 -0
- package/dist/discovery/rate-band.js.map +1 -0
- package/dist/escrow-generation.d.ts +81 -0
- package/dist/escrow-generation.d.ts.map +1 -0
- package/dist/escrow-generation.js +76 -0
- package/dist/escrow-generation.js.map +1 -0
- package/dist/frameworks/agentkit.d.ts +8 -4
- package/dist/frameworks/agentkit.d.ts.map +1 -1
- package/dist/frameworks/agentkit.js +27 -10
- package/dist/frameworks/agentkit.js.map +1 -1
- package/dist/frameworks/eliza.d.ts +3 -3
- package/dist/frameworks/eliza.d.ts.map +1 -1
- package/dist/frameworks/eliza.js +15 -6
- package/dist/frameworks/eliza.js.map +1 -1
- package/dist/frameworks/langchain.d.ts.map +1 -1
- package/dist/frameworks/langchain.js +8 -0
- package/dist/frameworks/langchain.js.map +1 -1
- package/dist/gateway/caller-auth-gateway.d.ts +83 -31
- package/dist/gateway/caller-auth-gateway.d.ts.map +1 -1
- package/dist/gateway/caller-auth-gateway.js +180 -27
- package/dist/gateway/caller-auth-gateway.js.map +1 -1
- package/dist/gateway/http-server.d.ts +128 -44
- package/dist/gateway/http-server.d.ts.map +1 -1
- package/dist/gateway/http-server.js +506 -155
- package/dist/gateway/http-server.js.map +1 -1
- package/dist/gateway/probe-auth.d.ts +112 -0
- package/dist/gateway/probe-auth.d.ts.map +1 -0
- package/dist/gateway/probe-auth.js +127 -0
- package/dist/gateway/probe-auth.js.map +1 -0
- package/dist/gateway/signed-rate-bounds.d.ts +51 -0
- package/dist/gateway/signed-rate-bounds.d.ts.map +1 -0
- package/dist/gateway/signed-rate-bounds.js +94 -0
- package/dist/gateway/signed-rate-bounds.js.map +1 -0
- package/dist/gateway/x402-opener-mode.d.ts +252 -0
- package/dist/gateway/x402-opener-mode.d.ts.map +1 -0
- package/dist/gateway/x402-opener-mode.js +772 -0
- package/dist/gateway/x402-opener-mode.js.map +1 -0
- package/dist/index.d.ts +6 -2
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +10 -5
- package/dist/index.js.map +1 -1
- package/dist/mcp/server.d.ts +64 -1
- package/dist/mcp/server.d.ts.map +1 -1
- package/dist/mcp/server.js +247 -37
- package/dist/mcp/server.js.map +1 -1
- package/dist/mcp/x402-tools.d.ts +109 -0
- package/dist/mcp/x402-tools.d.ts.map +1 -0
- package/dist/mcp/x402-tools.js +554 -0
- package/dist/mcp/x402-tools.js.map +1 -0
- package/dist/network.d.ts +119 -0
- package/dist/network.d.ts.map +1 -0
- package/dist/network.js +199 -0
- package/dist/network.js.map +1 -0
- package/dist/sdk/client.d.ts +13 -0
- package/dist/sdk/client.d.ts.map +1 -1
- package/dist/sdk/client.js +15 -0
- package/dist/sdk/client.js.map +1 -1
- package/dist/sdk/invoke.d.ts +4 -0
- package/dist/sdk/invoke.d.ts.map +1 -1
- package/dist/sdk/invoke.js +2 -5
- package/dist/sdk/invoke.js.map +1 -1
- package/dist/wallet/autonomous-wallet-broker.d.ts +3 -0
- package/dist/wallet/autonomous-wallet-broker.d.ts.map +1 -1
- package/dist/wallet/autonomous-wallet-broker.js +27 -23
- package/dist/wallet/autonomous-wallet-broker.js.map +1 -1
- package/dist/wallet/autonomous-wallet-protocol.d.ts +8 -2
- package/dist/wallet/autonomous-wallet-protocol.d.ts.map +1 -1
- package/dist/wallet/autonomous-wallet-protocol.js +9 -2
- package/dist/wallet/autonomous-wallet-protocol.js.map +1 -1
- package/dist/wallet/autonomous-wallet.d.ts.map +1 -1
- package/dist/wallet/autonomous-wallet.js +3 -2
- package/dist/wallet/autonomous-wallet.js.map +1 -1
- package/dist/wallet/broker-escrows.d.ts +222 -0
- package/dist/wallet/broker-escrows.d.ts.map +1 -0
- package/dist/wallet/broker-escrows.js +36 -0
- package/dist/wallet/broker-escrows.js.map +1 -0
- package/dist/wallet/lifecycle.d.ts +21 -5
- package/dist/wallet/lifecycle.d.ts.map +1 -1
- package/dist/wallet/lifecycle.js +32 -12
- package/dist/wallet/lifecycle.js.map +1 -1
- package/dist/wallet/privy-broker-server.d.ts.map +1 -1
- package/dist/wallet/privy-broker-server.js +31 -26
- package/dist/wallet/privy-broker-server.js.map +1 -1
- package/dist/wallet/privy-session-broker.d.ts +14 -5
- package/dist/wallet/privy-session-broker.d.ts.map +1 -1
- package/dist/wallet/privy-session-broker.js +29 -17
- package/dist/wallet/privy-session-broker.js.map +1 -1
- package/dist/wallet/privy-session-provider.d.ts +3 -1
- package/dist/wallet/privy-session-provider.d.ts.map +1 -1
- package/dist/wallet/privy-session-provider.js +5 -3
- package/dist/wallet/privy-session-provider.js.map +1 -1
- package/dist/wallet/provider.d.ts.map +1 -1
- package/dist/wallet/provider.js +15 -8
- package/dist/wallet/provider.js.map +1 -1
- package/dist/x402/facilitator.d.ts +3 -30
- package/dist/x402/facilitator.d.ts.map +1 -1
- package/dist/x402/facilitator.js +0 -27
- package/dist/x402/facilitator.js.map +1 -1
- package/dist/x402-buyer/guarded-fetch.d.ts +51 -0
- package/dist/x402-buyer/guarded-fetch.d.ts.map +1 -0
- package/dist/x402-buyer/guarded-fetch.js +147 -0
- package/dist/x402-buyer/guarded-fetch.js.map +1 -0
- package/dist/x402-buyer/index.d.ts +10 -0
- package/dist/x402-buyer/index.d.ts.map +1 -0
- package/dist/x402-buyer/index.js +10 -0
- package/dist/x402-buyer/index.js.map +1 -0
- package/dist/x402-buyer/pay.d.ts +157 -0
- package/dist/x402-buyer/pay.d.ts.map +1 -0
- package/dist/x402-buyer/pay.js +366 -0
- package/dist/x402-buyer/pay.js.map +1 -0
- package/dist/x402-opener/abi.d.ts +684 -0
- package/dist/x402-opener/abi.d.ts.map +1 -0
- package/dist/x402-opener/abi.js +880 -0
- package/dist/x402-opener/abi.js.map +1 -0
- package/dist/x402-opener/facilitator-entry.d.ts +3 -0
- package/dist/x402-opener/facilitator-entry.d.ts.map +1 -0
- package/dist/x402-opener/facilitator-entry.js +40 -0
- package/dist/x402-opener/facilitator-entry.js.map +1 -0
- package/dist/x402-opener/facilitator-server.d.ts +209 -0
- package/dist/x402-opener/facilitator-server.d.ts.map +1 -0
- package/dist/x402-opener/facilitator-server.js +762 -0
- package/dist/x402-opener/facilitator-server.js.map +1 -0
- package/dist/x402-opener/index.d.ts +14 -0
- package/dist/x402-opener/index.d.ts.map +1 -0
- package/dist/x402-opener/index.js +14 -0
- package/dist/x402-opener/index.js.map +1 -0
- package/dist/x402-opener/listing-resolver.d.ts +55 -0
- package/dist/x402-opener/listing-resolver.d.ts.map +1 -0
- package/dist/x402-opener/listing-resolver.js +125 -0
- package/dist/x402-opener/listing-resolver.js.map +1 -0
- package/dist/x402-opener/refund-relay.d.ts +266 -0
- package/dist/x402-opener/refund-relay.d.ts.map +1 -0
- package/dist/x402-opener/refund-relay.js +1341 -0
- package/dist/x402-opener/refund-relay.js.map +1 -0
- package/dist/x402-opener/relayer-queue.d.ts +14 -0
- package/dist/x402-opener/relayer-queue.d.ts.map +1 -0
- package/dist/x402-opener/relayer-queue.js +18 -0
- package/dist/x402-opener/relayer-queue.js.map +1 -0
- package/dist/x402-opener/scheme.d.ts +296 -0
- package/dist/x402-opener/scheme.d.ts.map +1 -0
- package/dist/x402-opener/scheme.js +1035 -0
- package/dist/x402-opener/scheme.js.map +1 -0
- package/dist/x402-opener/terms.d.ts +165 -0
- package/dist/x402-opener/terms.d.ts.map +1 -0
- package/dist/x402-opener/terms.js +304 -0
- package/dist/x402-opener/terms.js.map +1 -0
- package/dist/zktls/reclaim.d.ts +2 -2
- package/dist/zktls/t2-delivery-proof.d.ts +6 -6
- package/docs/agent-layer.md +3 -2
- package/docs/autonomous-privy-wallet.md +188 -0
- package/docs/cli.md +265 -34
- package/docs/langchain.md +5 -0
- package/docs/mcp-reference.md +91 -5
- package/docs/probe-capability.md +191 -0
- package/docs/quickstart.md +39 -4
- package/docs/threat-model.md +20 -0
- package/docs/x402.md +766 -593
- package/package.json +19 -17
- package/src/capability/probe-capability.ts +355 -0
- package/src/cli/args.ts +29 -0
- package/src/cli/commands/claim.ts +168 -33
- package/src/cli/commands/close.ts +36 -3
- package/src/cli/commands/invoke.ts +5 -2
- package/src/cli/commands/mcp.ts +18 -2
- package/src/cli/commands/open.ts +75 -4
- package/src/cli/commands/pay.ts +584 -0
- package/src/cli/commands/reclaim-unverified.ts +8 -2
- package/src/cli/commands/reclaim.ts +277 -19
- package/src/cli/commands/refund.ts +475 -0
- package/src/cli/commands/status.ts +28 -2
- package/src/cli/commands/streams.ts +10 -14
- package/src/cli/commands/watch.ts +11 -1
- package/src/cli/config.ts +139 -52
- package/src/cli/context.ts +16 -0
- package/src/cli/deps.ts +111 -1
- package/src/cli/errors.ts +24 -1
- package/src/cli/escape-hatch.ts +19 -5
- package/src/cli/listings.ts +43 -10
- package/src/cli/preflight.ts +36 -21
- package/src/cli/privy.ts +4 -2
- package/src/cli/progress.ts +21 -2
- package/src/cli/reclaimability.ts +154 -0
- package/src/cli/run.ts +77 -21
- package/src/cli/scan-range.ts +2 -2
- package/src/cli/status.ts +454 -44
- package/src/cli/wallet.ts +45 -8
- package/src/discovery/rate-band.ts +172 -0
- package/src/escrow-generation.ts +135 -0
- package/src/frameworks/agentkit.ts +45 -11
- package/src/frameworks/eliza.ts +27 -5
- package/src/frameworks/langchain.ts +14 -0
- package/src/gateway/caller-auth-gateway.ts +320 -68
- package/src/gateway/http-server.ts +717 -220
- package/src/gateway/probe-auth.ts +191 -0
- package/src/gateway/signed-rate-bounds.ts +164 -0
- package/src/gateway/x402-opener-mode.ts +1171 -0
- package/src/index.ts +82 -19
- package/src/mcp/server.ts +351 -42
- package/src/mcp/x402-tools.ts +785 -0
- package/src/network.ts +302 -0
- package/src/sdk/client.ts +25 -0
- package/src/sdk/invoke.ts +6 -5
- package/src/wallet/autonomous-wallet-broker.ts +46 -20
- package/src/wallet/autonomous-wallet-protocol.ts +11 -2
- package/src/wallet/autonomous-wallet.ts +4 -2
- package/src/wallet/broker-escrows.ts +66 -0
- package/src/wallet/lifecycle.ts +53 -18
- package/src/wallet/privy-broker-server.ts +35 -25
- package/src/wallet/privy-session-broker.ts +58 -25
- package/src/wallet/privy-session-provider.ts +7 -3
- package/src/wallet/provider.ts +20 -15
- package/src/x402/facilitator.ts +3 -43
- package/src/x402-buyer/guarded-fetch.ts +213 -0
- package/src/x402-buyer/index.ts +9 -0
- package/src/x402-buyer/pay.ts +555 -0
- package/src/x402-opener/abi.ts +881 -0
- package/src/x402-opener/facilitator-entry.ts +48 -0
- package/src/x402-opener/facilitator-server.ts +1114 -0
- package/src/x402-opener/index.ts +13 -0
- package/src/x402-opener/listing-resolver.ts +202 -0
- package/src/x402-opener/refund-relay.ts +1873 -0
- package/src/x402-opener/relayer-queue.ts +18 -0
- package/src/x402-opener/scheme.ts +1551 -0
- package/src/x402-opener/terms.ts +453 -0
- package/dist/gateway/x402-mode.d.ts +0 -123
- package/dist/gateway/x402-mode.d.ts.map +0 -1
- package/dist/gateway/x402-mode.js +0 -212
- package/dist/gateway/x402-mode.js.map +0 -1
- package/dist/x402/delivery-oracle.d.ts +0 -108
- package/dist/x402/delivery-oracle.d.ts.map +0 -1
- package/dist/x402/delivery-oracle.js +0 -174
- package/dist/x402/delivery-oracle.js.map +0 -1
- package/dist/x402/facilitator-server-entry.d.ts +0 -3
- package/dist/x402/facilitator-server-entry.d.ts.map +0 -1
- package/dist/x402/facilitator-server-entry.js +0 -27
- package/dist/x402/facilitator-server-entry.js.map +0 -1
- package/dist/x402/facilitator-server.d.ts +0 -73
- package/dist/x402/facilitator-server.d.ts.map +0 -1
- package/dist/x402/facilitator-server.js +0 -305
- package/dist/x402/facilitator-server.js.map +0 -1
- package/dist/x402/payment-requirements.d.ts +0 -106
- package/dist/x402/payment-requirements.d.ts.map +0 -1
- package/dist/x402/payment-requirements.js +0 -138
- package/dist/x402/payment-requirements.js.map +0 -1
- package/dist/x402/relayer.d.ts +0 -41
- package/dist/x402/relayer.d.ts.map +0 -1
- package/dist/x402/relayer.js +0 -64
- package/dist/x402/relayer.js.map +0 -1
- package/dist/x402/resource-index.d.ts +0 -75
- package/dist/x402/resource-index.d.ts.map +0 -1
- package/dist/x402/resource-index.js +0 -126
- package/dist/x402/resource-index.js.map +0 -1
- package/dist/x402/verified-delivery-facilitator.d.ts +0 -285
- package/dist/x402/verified-delivery-facilitator.d.ts.map +0 -1
- package/dist/x402/verified-delivery-facilitator.js +0 -423
- package/dist/x402/verified-delivery-facilitator.js.map +0 -1
- package/src/gateway/x402-mode.ts +0 -350
- package/src/x402/delivery-oracle.ts +0 -285
- package/src/x402/facilitator-server-entry.ts +0 -35
- package/src/x402/facilitator-server.ts +0 -445
- package/src/x402/payment-requirements.ts +0 -231
- package/src/x402/relayer.ts +0 -122
- package/src/x402/resource-index.ts +0 -228
- package/src/x402/verified-delivery-facilitator.ts +0 -744
|
@@ -0,0 +1,453 @@
|
|
|
1
|
+
import {
|
|
2
|
+
InvalidUpfrontTermsError,
|
|
3
|
+
validateUpfrontTerms,
|
|
4
|
+
} from "@absol-labs/shared";
|
|
5
|
+
import { getAddress, isAddress, isHex, type Address, type Hex } from "viem";
|
|
6
|
+
|
|
7
|
+
/**
|
|
8
|
+
* Shared vocabulary of the x402 v2 escrow-opener path (metrik-agent#116).
|
|
9
|
+
*
|
|
10
|
+
* A standard x402 v2 `exact` payment (an EIP-3009 `transferWithAuthorization`)
|
|
11
|
+
* is settled through the ownerless `X402StreamOpenerFactory`
|
|
12
|
+
* (metrik-contracts#48): the x402 `payTo` is the CREATE2 address of the opener
|
|
13
|
+
* for one immutable set of stream {@link OpenerTerms}, so the payer's signature
|
|
14
|
+
* (which binds `to`) commits to those terms, and the opener turns the payment
|
|
15
|
+
* into an ordinary `StreamEscrowV2` stream with `deposit = amount`.
|
|
16
|
+
*
|
|
17
|
+
* This module has no network or package side effects: it is the pure,
|
|
18
|
+
* dependency-free part shared by the facilitator and the gateway.
|
|
19
|
+
*/
|
|
20
|
+
|
|
21
|
+
/** Scheme name. The standard x402 `exact` scheme, nothing Metrik-specific. */
|
|
22
|
+
export const OPENER_SCHEME = "exact" as const;
|
|
23
|
+
|
|
24
|
+
/*
|
|
25
|
+
* Network, USDC, escrow, factory and oracle defaults are NOT constants here:
|
|
26
|
+
* they come from the `@absol-labs/sdk` network registry (see `../network.ts`),
|
|
27
|
+
* so a new deployment is a registry change, never an edit to this module.
|
|
28
|
+
*/
|
|
29
|
+
|
|
30
|
+
/** Public docs for the x402 opener path, linked from the 402. */
|
|
31
|
+
export const DEFAULT_OPENER_DOCS_URL =
|
|
32
|
+
"https://github.com/Absol-Labs/metrik-agent/blob/main/docs/x402.md";
|
|
33
|
+
|
|
34
|
+
/** Longest informational link accepted in `extra.metrikStreamOpener`. */
|
|
35
|
+
const MAX_LINK_LENGTH = 2048;
|
|
36
|
+
|
|
37
|
+
/**
|
|
38
|
+
* Key under `PaymentRequirements.extra` that carries the opener terms. The
|
|
39
|
+
* facilitator reads the terms ONLY from here, recomputes the opener address
|
|
40
|
+
* on-chain and requires it to equal `payTo`, so a tampered value can never
|
|
41
|
+
* redirect funds: it just fails verification.
|
|
42
|
+
*/
|
|
43
|
+
export const OPENER_EXTRA_KEY = "metrikStreamOpener" as const;
|
|
44
|
+
|
|
45
|
+
/** `uint64` ceiling for `maxDuration`. */
|
|
46
|
+
const MAX_UINT64 = (1n << 64n) - 1n;
|
|
47
|
+
|
|
48
|
+
/** Immutable per-listing stream terms, mirroring the Solidity `Terms` struct. */
|
|
49
|
+
export interface OpenerTerms {
|
|
50
|
+
readonly operator: Address;
|
|
51
|
+
readonly serviceRef: Hex;
|
|
52
|
+
/** USDC base units per second. */
|
|
53
|
+
readonly ratePerSecond: bigint;
|
|
54
|
+
/** Seconds. */
|
|
55
|
+
readonly maxDuration: bigint;
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
/**
|
|
59
|
+
* Which opener contract a factory deploys: `"stream"` (`X402StreamOpener`,
|
|
60
|
+
* 4-field terms, the whole payment funds a stream) or `"upfront"`
|
|
61
|
+
* (`X402UpfrontStreamOpener`, 6-field terms: a fixed `price` whose
|
|
62
|
+
* non-refundable `upfrontAmount` is paid to the seller at settlement and whose
|
|
63
|
+
* remainder funds a stream). Decided by WHICH configured factory a quote names,
|
|
64
|
+
* never by the wire fields alone.
|
|
65
|
+
*/
|
|
66
|
+
export type OpenerKind = "stream" | "upfront";
|
|
67
|
+
|
|
68
|
+
/** `termsVersion` of each opener kind's `extra.metrikStreamOpener` (as the SDK checks it). */
|
|
69
|
+
export const OPENER_TERMS_VERSION = {
|
|
70
|
+
stream: "stream-1",
|
|
71
|
+
upfront: "upfront-1",
|
|
72
|
+
} as const satisfies Record<OpenerKind, string>;
|
|
73
|
+
|
|
74
|
+
/**
|
|
75
|
+
* The 6-field terms of an `X402UpfrontStreamOpener` (metrik-contracts#54),
|
|
76
|
+
* mirroring the Solidity struct. Every field is committed by the `payTo`.
|
|
77
|
+
*/
|
|
78
|
+
export interface UpfrontOpenerTerms extends OpenerTerms {
|
|
79
|
+
/** The exact x402 amount: the opener accepts this value and nothing else. */
|
|
80
|
+
readonly price: bigint;
|
|
81
|
+
/** NON-REFUNDABLE part paid to the seller (net of the protocol fee) at settlement. `<= price`. */
|
|
82
|
+
readonly upfrontAmount: bigint;
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
/** The refundable, metered part of an upfront opener's price (the stream deposit). */
|
|
86
|
+
export function upfrontRefundable(terms: UpfrontOpenerTerms): bigint {
|
|
87
|
+
return terms.price - terms.upfrontAmount;
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
/** True when an upfront opener opens no stream at all (`upfrontAmount == price`). */
|
|
91
|
+
export function isUpfrontOnly(terms: UpfrontOpenerTerms): boolean {
|
|
92
|
+
return terms.price > 0n && terms.upfrontAmount === terms.price;
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
/**
|
|
96
|
+
* The upfront terms a gateway may quote: exactly the factory's
|
|
97
|
+
* `validateTerms` (via `@absol-labs/shared`'s `validateUpfrontTerms`, so a
|
|
98
|
+
* `payTo` no transaction can deploy is never quoted), a fixed non-zero price,
|
|
99
|
+
* and a metered part (`price - upfrontAmount`) the stream can actually earn
|
|
100
|
+
* (`<= ratePerSecond * maxDuration`) — the SDK buyer refuses anything else.
|
|
101
|
+
*/
|
|
102
|
+
export function assertValidUpfrontTerms(terms: UpfrontOpenerTerms): void {
|
|
103
|
+
assertValidTerms(terms);
|
|
104
|
+
try {
|
|
105
|
+
validateUpfrontTerms({
|
|
106
|
+
operator: getAddress(terms.operator),
|
|
107
|
+
serviceRef: terms.serviceRef.toLowerCase() as Hex,
|
|
108
|
+
ratePerSecond: terms.ratePerSecond,
|
|
109
|
+
maxDuration: terms.maxDuration,
|
|
110
|
+
price: terms.price,
|
|
111
|
+
upfrontAmount: terms.upfrontAmount,
|
|
112
|
+
});
|
|
113
|
+
} catch (error) {
|
|
114
|
+
throw new InvalidOpenerTermsError(
|
|
115
|
+
error instanceof InvalidUpfrontTermsError || error instanceof Error
|
|
116
|
+
? error.message
|
|
117
|
+
: String(error),
|
|
118
|
+
);
|
|
119
|
+
}
|
|
120
|
+
if (terms.price <= 0n) {
|
|
121
|
+
throw new InvalidOpenerTermsError(
|
|
122
|
+
"an upfront opener needs a fixed price > 0",
|
|
123
|
+
);
|
|
124
|
+
}
|
|
125
|
+
if (upfrontRefundable(terms) > maxEarnable(terms)) {
|
|
126
|
+
throw new InvalidOpenerTermsError(
|
|
127
|
+
`the metered part ${upfrontRefundable(terms)} (price - upfrontAmount) exceeds ratePerSecond * maxDuration (${maxEarnable(terms)})`,
|
|
128
|
+
);
|
|
129
|
+
}
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
/** Solidity-tuple view of 6-field upfront terms for viem contract calls. */
|
|
133
|
+
export function upfrontTermsTuple(terms: UpfrontOpenerTerms): {
|
|
134
|
+
readonly operator: Address;
|
|
135
|
+
readonly serviceRef: Hex;
|
|
136
|
+
readonly ratePerSecond: bigint;
|
|
137
|
+
readonly maxDuration: bigint;
|
|
138
|
+
readonly price: bigint;
|
|
139
|
+
readonly upfrontAmount: bigint;
|
|
140
|
+
} {
|
|
141
|
+
return {
|
|
142
|
+
...termsTuple(terms),
|
|
143
|
+
price: terms.price,
|
|
144
|
+
upfrontAmount: terms.upfrontAmount,
|
|
145
|
+
};
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
/** JSON-safe projection of {@link OpenerTerms} plus the factory that prices them. */
|
|
149
|
+
export interface OpenerTermsExtra {
|
|
150
|
+
readonly factory: Address;
|
|
151
|
+
readonly operator: Address;
|
|
152
|
+
readonly serviceRef: Hex;
|
|
153
|
+
readonly ratePerSecond: string;
|
|
154
|
+
readonly maxDuration: string;
|
|
155
|
+
/** Upfront openers only: the exact price (base units). */
|
|
156
|
+
readonly price?: string;
|
|
157
|
+
/** Upfront openers only: the non-refundable per-call part (base units). */
|
|
158
|
+
readonly upfrontAmount?: string;
|
|
159
|
+
/** `stream-1` / `upfront-1`; optional, must match the factory's kind when present. */
|
|
160
|
+
readonly termsVersion?: string;
|
|
161
|
+
/**
|
|
162
|
+
* Informational only (metrik-agent#119): where the payer gets unearned money
|
|
163
|
+
* back without ETH, as a template containing `{streamId}`. Never used for
|
|
164
|
+
* settlement; the facilitator validates it is an http(s) link and ignores it.
|
|
165
|
+
*/
|
|
166
|
+
readonly refundUrl?: string;
|
|
167
|
+
/** Informational only: docs for this payment path. */
|
|
168
|
+
readonly docsUrl?: string;
|
|
169
|
+
}
|
|
170
|
+
|
|
171
|
+
/** True for an absolute http(s) URL of sane length. */
|
|
172
|
+
export function isHttpLink(value: unknown): value is string {
|
|
173
|
+
if (typeof value !== "string" || value.length > MAX_LINK_LENGTH) return false;
|
|
174
|
+
try {
|
|
175
|
+
const url = new URL(value);
|
|
176
|
+
return url.protocol === "https:" || url.protocol === "http:";
|
|
177
|
+
} catch {
|
|
178
|
+
return false;
|
|
179
|
+
}
|
|
180
|
+
}
|
|
181
|
+
|
|
182
|
+
export class InvalidOpenerTermsError extends Error {
|
|
183
|
+
constructor(message: string) {
|
|
184
|
+
super(message);
|
|
185
|
+
this.name = "InvalidOpenerTermsError";
|
|
186
|
+
}
|
|
187
|
+
}
|
|
188
|
+
|
|
189
|
+
/** Parses a non-negative base-10 integer string. Throws on anything else. */
|
|
190
|
+
export function parseUintString(value: unknown, field: string): bigint {
|
|
191
|
+
if (typeof value !== "string" || !/^(0|[1-9]\d*)$/.test(value)) {
|
|
192
|
+
throw new InvalidOpenerTermsError(
|
|
193
|
+
`${field} must be a base-10 integer string without sign or leading zeros`,
|
|
194
|
+
);
|
|
195
|
+
}
|
|
196
|
+
return BigInt(value);
|
|
197
|
+
}
|
|
198
|
+
|
|
199
|
+
/**
|
|
200
|
+
* Validates terms the way the factory's `deploy` does (non-zero operator, rate
|
|
201
|
+
* and duration, `maxDuration` within `uint64`) plus the shape checks the
|
|
202
|
+
* contract cannot do for us (32-byte serviceRef).
|
|
203
|
+
*/
|
|
204
|
+
export function assertValidTerms(terms: OpenerTerms): void {
|
|
205
|
+
if (!isAddress(terms.operator, { strict: false })) {
|
|
206
|
+
throw new InvalidOpenerTermsError("operator must be an EVM address");
|
|
207
|
+
}
|
|
208
|
+
if (/^0x0{40}$/i.test(terms.operator)) {
|
|
209
|
+
throw new InvalidOpenerTermsError("operator must not be the zero address");
|
|
210
|
+
}
|
|
211
|
+
if (
|
|
212
|
+
!isHex(terms.serviceRef, { strict: true }) ||
|
|
213
|
+
terms.serviceRef.length !== 66
|
|
214
|
+
) {
|
|
215
|
+
throw new InvalidOpenerTermsError("serviceRef must be a 32-byte hex value");
|
|
216
|
+
}
|
|
217
|
+
if (terms.ratePerSecond <= 0n) {
|
|
218
|
+
throw new InvalidOpenerTermsError("ratePerSecond must be > 0");
|
|
219
|
+
}
|
|
220
|
+
if (terms.maxDuration <= 0n || terms.maxDuration > MAX_UINT64) {
|
|
221
|
+
throw new InvalidOpenerTermsError(
|
|
222
|
+
"maxDuration must be > 0 and fit in uint64",
|
|
223
|
+
);
|
|
224
|
+
}
|
|
225
|
+
}
|
|
226
|
+
|
|
227
|
+
/** The largest deposit a stream on these terms can ever earn out: `rate * maxDuration`. */
|
|
228
|
+
export function maxEarnable(terms: OpenerTerms): bigint {
|
|
229
|
+
return terms.ratePerSecond * terms.maxDuration;
|
|
230
|
+
}
|
|
231
|
+
|
|
232
|
+
/**
|
|
233
|
+
* The price (= stream deposit) must be positive and must not exceed what the
|
|
234
|
+
* stream can ever accrue. A deposit above `rate * maxDuration` would lock money
|
|
235
|
+
* the seller can never earn, reclaimable only by a second buyer action.
|
|
236
|
+
*/
|
|
237
|
+
export function assertValidPrice(price: bigint, terms: OpenerTerms): void {
|
|
238
|
+
if (price <= 0n) {
|
|
239
|
+
throw new InvalidOpenerTermsError("price must be > 0");
|
|
240
|
+
}
|
|
241
|
+
if (price > maxEarnable(terms)) {
|
|
242
|
+
throw new InvalidOpenerTermsError(
|
|
243
|
+
`price ${price} exceeds ratePerSecond * maxDuration (${maxEarnable(terms)})`,
|
|
244
|
+
);
|
|
245
|
+
}
|
|
246
|
+
}
|
|
247
|
+
|
|
248
|
+
export function termsToExtra(
|
|
249
|
+
factory: Address,
|
|
250
|
+
terms: OpenerTerms,
|
|
251
|
+
): OpenerTermsExtra {
|
|
252
|
+
return {
|
|
253
|
+
factory: getAddress(factory),
|
|
254
|
+
operator: getAddress(terms.operator),
|
|
255
|
+
serviceRef: terms.serviceRef.toLowerCase() as Hex,
|
|
256
|
+
ratePerSecond: terms.ratePerSecond.toString(),
|
|
257
|
+
maxDuration: terms.maxDuration.toString(),
|
|
258
|
+
};
|
|
259
|
+
}
|
|
260
|
+
|
|
261
|
+
/** The 402 `extra.metrikStreamOpener` terms of an upfront opener quote. */
|
|
262
|
+
export function upfrontTermsToExtra(
|
|
263
|
+
factory: Address,
|
|
264
|
+
terms: UpfrontOpenerTerms,
|
|
265
|
+
): OpenerTermsExtra {
|
|
266
|
+
return {
|
|
267
|
+
factory: getAddress(factory),
|
|
268
|
+
termsVersion: OPENER_TERMS_VERSION.upfront,
|
|
269
|
+
operator: getAddress(terms.operator),
|
|
270
|
+
serviceRef: terms.serviceRef.toLowerCase() as Hex,
|
|
271
|
+
ratePerSecond: terms.ratePerSecond.toString(),
|
|
272
|
+
maxDuration: terms.maxDuration.toString(),
|
|
273
|
+
price: terms.price.toString(),
|
|
274
|
+
upfrontAmount: terms.upfrontAmount.toString(),
|
|
275
|
+
};
|
|
276
|
+
}
|
|
277
|
+
|
|
278
|
+
/**
|
|
279
|
+
* Reads opener terms from an untrusted `PaymentRequirements.extra`. Every field
|
|
280
|
+
* is re-validated; unknown keys under the opener object are rejected so the
|
|
281
|
+
* wire shape cannot drift silently. `price` / `upfrontAmount` are returned as
|
|
282
|
+
* `upfront` when present (both or neither); whether they are REQUIRED or
|
|
283
|
+
* FORBIDDEN depends on the factory's kind, which only the caller knows.
|
|
284
|
+
*/
|
|
285
|
+
export function termsFromExtra(extra: unknown): {
|
|
286
|
+
readonly factory: Address;
|
|
287
|
+
readonly terms: OpenerTerms;
|
|
288
|
+
readonly upfront?: {
|
|
289
|
+
readonly price: bigint;
|
|
290
|
+
readonly upfrontAmount: bigint;
|
|
291
|
+
};
|
|
292
|
+
readonly termsVersion?: string;
|
|
293
|
+
} {
|
|
294
|
+
if (typeof extra !== "object" || extra === null) {
|
|
295
|
+
throw new InvalidOpenerTermsError("requirements.extra is missing");
|
|
296
|
+
}
|
|
297
|
+
const raw = (extra as Record<string, unknown>)[OPENER_EXTRA_KEY];
|
|
298
|
+
if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
|
|
299
|
+
throw new InvalidOpenerTermsError(
|
|
300
|
+
`requirements.extra.${OPENER_EXTRA_KEY} is missing`,
|
|
301
|
+
);
|
|
302
|
+
}
|
|
303
|
+
const record = raw as Record<string, unknown>;
|
|
304
|
+
const allowed = new Set([
|
|
305
|
+
"factory",
|
|
306
|
+
"operator",
|
|
307
|
+
"serviceRef",
|
|
308
|
+
"ratePerSecond",
|
|
309
|
+
"maxDuration",
|
|
310
|
+
"price",
|
|
311
|
+
"upfrontAmount",
|
|
312
|
+
"termsVersion",
|
|
313
|
+
"refundUrl",
|
|
314
|
+
"docsUrl",
|
|
315
|
+
]);
|
|
316
|
+
for (const key of Object.keys(record)) {
|
|
317
|
+
if (!allowed.has(key)) {
|
|
318
|
+
throw new InvalidOpenerTermsError(
|
|
319
|
+
`unknown key ${key} in requirements.extra.${OPENER_EXTRA_KEY}`,
|
|
320
|
+
);
|
|
321
|
+
}
|
|
322
|
+
}
|
|
323
|
+
for (const link of ["refundUrl", "docsUrl"] as const) {
|
|
324
|
+
if (record[link] !== undefined && !isHttpLink(record[link])) {
|
|
325
|
+
throw new InvalidOpenerTermsError(
|
|
326
|
+
`${link} in requirements.extra.${OPENER_EXTRA_KEY} must be an http(s) URL`,
|
|
327
|
+
);
|
|
328
|
+
}
|
|
329
|
+
}
|
|
330
|
+
const { factory, operator, serviceRef } = record;
|
|
331
|
+
if (typeof factory !== "string" || !isAddress(factory, { strict: false })) {
|
|
332
|
+
throw new InvalidOpenerTermsError("factory must be an EVM address");
|
|
333
|
+
}
|
|
334
|
+
if (typeof operator !== "string" || !isAddress(operator, { strict: false })) {
|
|
335
|
+
throw new InvalidOpenerTermsError("operator must be an EVM address");
|
|
336
|
+
}
|
|
337
|
+
if (typeof serviceRef !== "string") {
|
|
338
|
+
throw new InvalidOpenerTermsError("serviceRef must be a string");
|
|
339
|
+
}
|
|
340
|
+
const terms: OpenerTerms = {
|
|
341
|
+
operator: getAddress(operator),
|
|
342
|
+
serviceRef: serviceRef as Hex,
|
|
343
|
+
ratePerSecond: parseUintString(record.ratePerSecond, "ratePerSecond"),
|
|
344
|
+
maxDuration: parseUintString(record.maxDuration, "maxDuration"),
|
|
345
|
+
};
|
|
346
|
+
assertValidTerms(terms);
|
|
347
|
+
const termsVersion = record.termsVersion;
|
|
348
|
+
if (
|
|
349
|
+
termsVersion !== undefined &&
|
|
350
|
+
(typeof termsVersion !== "string" || termsVersion.length > 64)
|
|
351
|
+
) {
|
|
352
|
+
throw new InvalidOpenerTermsError("termsVersion must be a short string");
|
|
353
|
+
}
|
|
354
|
+
if ((record.price === undefined) !== (record.upfrontAmount === undefined)) {
|
|
355
|
+
throw new InvalidOpenerTermsError(
|
|
356
|
+
"price and upfrontAmount must be given together (an upfront opener's terms) or not at all",
|
|
357
|
+
);
|
|
358
|
+
}
|
|
359
|
+
const upfront =
|
|
360
|
+
record.price === undefined
|
|
361
|
+
? undefined
|
|
362
|
+
: {
|
|
363
|
+
price: parseUintString(record.price, "price"),
|
|
364
|
+
upfrontAmount: parseUintString(record.upfrontAmount, "upfrontAmount"),
|
|
365
|
+
};
|
|
366
|
+
return {
|
|
367
|
+
factory: getAddress(factory),
|
|
368
|
+
terms,
|
|
369
|
+
...(upfront === undefined ? {} : { upfront }),
|
|
370
|
+
...(termsVersion === undefined
|
|
371
|
+
? {}
|
|
372
|
+
: { termsVersion: termsVersion as string }),
|
|
373
|
+
};
|
|
374
|
+
}
|
|
375
|
+
|
|
376
|
+
/** Chain id encoded in an `eip155:<id>` CAIP-2 identifier. Throws otherwise. */
|
|
377
|
+
export function chainIdFromNetwork(network: string): number {
|
|
378
|
+
const match = /^eip155:([1-9]\d*)$/.exec(network);
|
|
379
|
+
if (match === null) {
|
|
380
|
+
throw new InvalidOpenerTermsError(
|
|
381
|
+
`network must be an eip155 CAIP-2 identifier, got ${network}`,
|
|
382
|
+
);
|
|
383
|
+
}
|
|
384
|
+
const chainId = Number(match[1]);
|
|
385
|
+
if (!Number.isSafeInteger(chainId)) {
|
|
386
|
+
throw new InvalidOpenerTermsError(`unsupported chain id in ${network}`);
|
|
387
|
+
}
|
|
388
|
+
return chainId;
|
|
389
|
+
}
|
|
390
|
+
|
|
391
|
+
/** Solidity-tuple view of terms for viem contract calls. */
|
|
392
|
+
export function termsTuple(terms: OpenerTerms): {
|
|
393
|
+
readonly operator: Address;
|
|
394
|
+
readonly serviceRef: Hex;
|
|
395
|
+
readonly ratePerSecond: bigint;
|
|
396
|
+
readonly maxDuration: bigint;
|
|
397
|
+
} {
|
|
398
|
+
return {
|
|
399
|
+
operator: getAddress(terms.operator),
|
|
400
|
+
serviceRef: terms.serviceRef,
|
|
401
|
+
ratePerSecond: terms.ratePerSecond,
|
|
402
|
+
maxDuration: terms.maxDuration,
|
|
403
|
+
};
|
|
404
|
+
}
|
|
405
|
+
|
|
406
|
+
/** A bazaar-shaped `{info: {input, output?}, schema?}` declaration. */
|
|
407
|
+
export interface X402SchemaDeclaration {
|
|
408
|
+
readonly info: {
|
|
409
|
+
readonly input: { readonly type: "http" } & Record<string, unknown>;
|
|
410
|
+
readonly output?: Record<string, unknown>;
|
|
411
|
+
};
|
|
412
|
+
readonly schema?: Record<string, unknown>;
|
|
413
|
+
}
|
|
414
|
+
|
|
415
|
+
/** Largest accepted schema declaration, serialized bytes. */
|
|
416
|
+
export const MAX_SCHEMA_DECLARATION_BYTES = 16 * 1024;
|
|
417
|
+
|
|
418
|
+
/** Validates a bazaar-shaped schema declaration. Throws on anything else. */
|
|
419
|
+
export function assertSchemaDeclaration(
|
|
420
|
+
value: unknown,
|
|
421
|
+
): asserts value is X402SchemaDeclaration {
|
|
422
|
+
if (JSON.stringify(value ?? null).length > MAX_SCHEMA_DECLARATION_BYTES) {
|
|
423
|
+
throw new Error(
|
|
424
|
+
`the schema declaration exceeds ${MAX_SCHEMA_DECLARATION_BYTES} bytes`,
|
|
425
|
+
);
|
|
426
|
+
}
|
|
427
|
+
const record = value as Record<string, unknown> | null;
|
|
428
|
+
const info = record?.info as Record<string, unknown> | undefined;
|
|
429
|
+
const input = info?.input as Record<string, unknown> | undefined;
|
|
430
|
+
if (
|
|
431
|
+
typeof record !== "object" ||
|
|
432
|
+
record === null ||
|
|
433
|
+
Array.isArray(record) ||
|
|
434
|
+
typeof info !== "object" ||
|
|
435
|
+
info === null ||
|
|
436
|
+
typeof input !== "object" ||
|
|
437
|
+
input === null ||
|
|
438
|
+
input.type !== "http" ||
|
|
439
|
+
(info.output !== undefined &&
|
|
440
|
+
(typeof info.output !== "object" || info.output === null)) ||
|
|
441
|
+
(record.schema !== undefined &&
|
|
442
|
+
(typeof record.schema !== "object" || record.schema === null))
|
|
443
|
+
) {
|
|
444
|
+
throw new Error(
|
|
445
|
+
'the schema declaration must be {info: {input: {type: "http", ...}, output?}, schema?}',
|
|
446
|
+
);
|
|
447
|
+
}
|
|
448
|
+
for (const key of Object.keys(record)) {
|
|
449
|
+
if (key !== "info" && key !== "schema") {
|
|
450
|
+
throw new Error(`unknown key ${key} in the schema declaration`);
|
|
451
|
+
}
|
|
452
|
+
}
|
|
453
|
+
}
|
|
@@ -1,123 +0,0 @@
|
|
|
1
|
-
import type { PaymentRequirements, SettleResponse, VerifyResponse } from "x402/types";
|
|
2
|
-
import { type SignedListingPayee, type X402AssetConfig, type X402PaymentRequiredBody } from "../x402/payment-requirements.js";
|
|
3
|
-
/**
|
|
4
|
-
* Standard x402 mode for the seller-side gateway (Tier 1).
|
|
5
|
-
*
|
|
6
|
-
* The gateway already authorizes requests that carry a Metrik
|
|
7
|
-
* `InvocationCapability` — a buyer with an open, funded, verified stream. That
|
|
8
|
-
* path is untouched. This module adds a SECOND, independent way in: a request
|
|
9
|
-
* with no capability gets an ordinary HTTP `402` carrying real x402
|
|
10
|
-
* `PaymentRequirements`, so an agent holding nothing but `x402-fetch` can pay
|
|
11
|
-
* per call without knowing Metrik exists.
|
|
12
|
-
*
|
|
13
|
-
* ## The two paths never overlap
|
|
14
|
-
*
|
|
15
|
-
* - capability header present -> stream path, exactly as before;
|
|
16
|
-
* - capability header absent, x402 mode on -> `402` + `PaymentRequirements`;
|
|
17
|
-
* - BOTH present -> rejected. A request that looks like both is ambiguous about
|
|
18
|
-
* which one is paying for it, and the failure mode of guessing is charging the
|
|
19
|
-
* caller twice for one call. Better a loud `400` than a silent double charge.
|
|
20
|
-
*
|
|
21
|
-
* ## The per-call price is the seller's, and is not signed
|
|
22
|
-
*
|
|
23
|
-
* `payTo` comes from the operator-signed descriptor (see
|
|
24
|
-
* `../x402/payment-requirements.ts`). The price does not — the descriptor has no
|
|
25
|
-
* per-call price field. It is the seller's own number on the seller's own
|
|
26
|
-
* gateway, which is legitimate, but a buyer cannot cross-check it against the
|
|
27
|
-
* registry the way they can cross-check the payee.
|
|
28
|
-
*/
|
|
29
|
-
/** Request header carrying the x402 payment payload (x402 v1). */
|
|
30
|
-
export declare const X402_PAYMENT_HEADER: "x-payment";
|
|
31
|
-
/** Response header carrying the settlement result (x402 v1). */
|
|
32
|
-
export declare const X402_PAYMENT_RESPONSE_HEADER: "x-payment-response";
|
|
33
|
-
/** The facilitator the gateway delegates verify/settle to. */
|
|
34
|
-
export interface X402FacilitatorClient {
|
|
35
|
-
verify(payload: unknown, requirements: PaymentRequirements): Promise<VerifyResponse>;
|
|
36
|
-
settle(payload: unknown, requirements: PaymentRequirements): Promise<SettleResponse>;
|
|
37
|
-
}
|
|
38
|
-
export interface HttpFacilitatorClientOptions {
|
|
39
|
-
/** Base URL of a facilitator exposing `/verify` and `/settle`. */
|
|
40
|
-
readonly url: string;
|
|
41
|
-
/**
|
|
42
|
-
* Shared secret for the facilitator's `/settle`. Sent as
|
|
43
|
-
* `Authorization: Bearer`. Metrik's own facilitator refuses to start a
|
|
44
|
-
* settling deployment without one, because `/settle` spends its gas.
|
|
45
|
-
*/
|
|
46
|
-
readonly token?: string;
|
|
47
|
-
readonly headers?: Readonly<Record<string, string>>;
|
|
48
|
-
readonly timeoutMs?: number;
|
|
49
|
-
readonly fetch?: typeof globalThis.fetch;
|
|
50
|
-
}
|
|
51
|
-
/**
|
|
52
|
-
* Talks to any x402 facilitator over HTTP — including Metrik's own
|
|
53
|
-
* (`../x402/facilitator-server.ts`), which is the point: a seller who wires this
|
|
54
|
-
* gateway to the Metrik facilitator gets a paywall whose payments stop when
|
|
55
|
-
* their own delivery stops being verifiable.
|
|
56
|
-
*/
|
|
57
|
-
export declare function createHttpFacilitatorClient(options: HttpFacilitatorClientOptions): X402FacilitatorClient;
|
|
58
|
-
/** Builds the `PaymentRequirements` quoted for a given request. */
|
|
59
|
-
export type X402Quoter = (request: {
|
|
60
|
-
readonly method: string;
|
|
61
|
-
readonly path: string;
|
|
62
|
-
}) => readonly PaymentRequirements[] | Promise<readonly PaymentRequirements[]>;
|
|
63
|
-
export interface ListingPriceQuoterOptions {
|
|
64
|
-
/** Projected from the OPERATOR-SIGNED descriptor. `payTo` comes from here. */
|
|
65
|
-
readonly listing: SignedListingPayee;
|
|
66
|
-
/** Public origin buyers reach this gateway on, e.g. `https://svc.example.com`. */
|
|
67
|
-
readonly resourceBaseUrl: string;
|
|
68
|
-
/** Per-call price in the asset's base units (micro-USDC). Seller-set, unsigned. */
|
|
69
|
-
readonly pricePerCallBaseUnits: bigint;
|
|
70
|
-
readonly chainId: number;
|
|
71
|
-
readonly description?: string;
|
|
72
|
-
readonly mimeType?: string;
|
|
73
|
-
readonly maxTimeoutSeconds?: number;
|
|
74
|
-
readonly asset?: X402AssetConfig;
|
|
75
|
-
}
|
|
76
|
-
/** One flat price per call, quoted against the request's own path. */
|
|
77
|
-
export declare function createListingPriceQuoter(options: ListingPriceQuoterOptions): X402Quoter;
|
|
78
|
-
export interface GatewayX402Mode {
|
|
79
|
-
readonly quote: X402Quoter;
|
|
80
|
-
readonly facilitator: X402FacilitatorClient;
|
|
81
|
-
}
|
|
82
|
-
/** Decoded, still-untrusted `X-PAYMENT` payload plus the quote it answers. */
|
|
83
|
-
export interface AcceptedX402Payment {
|
|
84
|
-
readonly payload: unknown;
|
|
85
|
-
readonly requirements: PaymentRequirements;
|
|
86
|
-
readonly payer?: string;
|
|
87
|
-
/**
|
|
88
|
-
* Unix seconds after which the signed authorization is no longer settleable
|
|
89
|
-
* (`validBefore`), when the payload carried one.
|
|
90
|
-
*
|
|
91
|
-
* The upstream runs BEFORE settlement, so an upstream slower than this window
|
|
92
|
-
* would produce its side effects and then fail to be paid for. The server
|
|
93
|
-
* bounds the upstream call by this instead of letting that happen.
|
|
94
|
-
*/
|
|
95
|
-
readonly validBefore?: number;
|
|
96
|
-
}
|
|
97
|
-
export type X402EvaluationOutcome = {
|
|
98
|
-
readonly outcome: "payment-required";
|
|
99
|
-
readonly body: X402PaymentRequiredBody;
|
|
100
|
-
} | {
|
|
101
|
-
readonly outcome: "accepted";
|
|
102
|
-
readonly payment: AcceptedX402Payment;
|
|
103
|
-
};
|
|
104
|
-
/**
|
|
105
|
-
* Evaluates the x402 half of a request. Returns either the `402` body to send or
|
|
106
|
-
* an accepted payment to settle after the upstream has been called.
|
|
107
|
-
*/
|
|
108
|
-
export declare function evaluateX402Request(request: {
|
|
109
|
-
readonly method: string;
|
|
110
|
-
readonly path: string;
|
|
111
|
-
}, paymentHeader: string | undefined, mode: GatewayX402Mode): Promise<X402EvaluationOutcome>;
|
|
112
|
-
/**
|
|
113
|
-
* Seconds of headroom the settlement leg needs after the upstream returns.
|
|
114
|
-
*
|
|
115
|
-
* The x402 `exact` verifier rejects an authorization whose `validBefore` is less
|
|
116
|
-
* than 6 s away, so an upstream allowed to run right up to the deadline would
|
|
117
|
-
* hand back a response that can never be settled. This leaves room for that
|
|
118
|
-
* check plus the settle round trip.
|
|
119
|
-
*/
|
|
120
|
-
export declare const X402_SETTLEMENT_HEADROOM_SECONDS = 10;
|
|
121
|
-
export declare function decodePaymentHeader(header: string): unknown;
|
|
122
|
-
export declare function encodeSettleResponseHeader(response: SettleResponse): string;
|
|
123
|
-
//# sourceMappingURL=x402-mode.d.ts.map
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"x402-mode.d.ts","sourceRoot":"","sources":["../../src/gateway/x402-mode.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,mBAAmB,EACnB,cAAc,EACd,cAAc,EACf,MAAM,YAAY,CAAC;AAEpB,OAAO,EAGL,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,KAAK,uBAAuB,EAC7B,MAAM,iCAAiC,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,kEAAkE;AAClE,eAAO,MAAM,mBAAmB,EAAG,WAAoB,CAAC;AAExD,gEAAgE;AAChE,eAAO,MAAM,4BAA4B,EAAG,oBAA6B,CAAC;AAE1E,8DAA8D;AAC9D,MAAM,WAAW,qBAAqB;IACpC,MAAM,CACJ,OAAO,EAAE,OAAO,EAChB,YAAY,EAAE,mBAAmB,GAChC,OAAO,CAAC,cAAc,CAAC,CAAC;IAC3B,MAAM,CACJ,OAAO,EAAE,OAAO,EAChB,YAAY,EAAE,mBAAmB,GAChC,OAAO,CAAC,cAAc,CAAC,CAAC;CAC5B;AAED,MAAM,WAAW,4BAA4B;IAC3C,kEAAkE;IAClE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACpD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CAC1C;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,4BAA4B,GACpC,qBAAqB,CAgDvB;AAED,mEAAmE;AACnE,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,EAAE;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB,KAAK,SAAS,mBAAmB,EAAE,GAAG,OAAO,CAAC,SAAS,mBAAmB,EAAE,CAAC,CAAC;AAE/E,MAAM,WAAW,yBAAyB;IACxC,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;IACrC,kFAAkF;IAClF,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,mFAAmF;IACnF,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,KAAK,CAAC,EAAE,eAAe,CAAC;CAClC;AAED,sEAAsE;AACtE,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,yBAAyB,GACjC,UAAU,CAkBZ;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,qBAAqB,CAAC;CAC7C;AAED,8EAA8E;AAC9E,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,YAAY,EAAE,mBAAmB,CAAC;IAC3C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;;OAOG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,MAAM,qBAAqB,GAC7B;IACE,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;IACrC,QAAQ,CAAC,IAAI,EAAE,uBAAuB,CAAC;CACxC,GACD;IAAE,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAA;CAAE,CAAC;AAE5E;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EAC3D,aAAa,EAAE,MAAM,GAAG,SAAS,EACjC,IAAI,EAAE,eAAe,GACpB,OAAO,CAAC,qBAAqB,CAAC,CAqFhC;AAeD;;;;;;;GAOG;AACH,eAAO,MAAM,gCAAgC,KAAK,CAAC;AAmBnD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAQ3D;AAED,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,cAAc,GAAG,MAAM,CAE3E"}
|