@cloudpayx/x402-pay 0.2.1 → 0.2.3

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.
Files changed (3) hide show
  1. package/README.before-0.2.3.bak +94 -0
  2. package/README.md +60 -65
  3. package/package.json +3 -7
package/README.before-0.2.3.bak ADDED
@@ -0,0 +1,94 @@
1
+ # cpX x402 Pay | XRPL Agent Payment SDK
2
+
3
+ **Purpose:** Let an unaffiliated, self-funded agent participate in the XRPL x402 economy without a cloudpayX registration, dashboard, Supabase session, or required wallet brand. This is an XRPL-native SDK for autonomous agents purchasing x402-protected resources.
4
+
5
+ The SDK supports wallet-agnostic signing, three-asset payment policies, spending controls, guarded signing, and validated-ledger reconciliation. Agents must use compatible XRPL signers and maintain sufficient funds.
6
+
7
+ ## Source
8
+
9
+ - `src/policy.ts` — strict, dependency-free XRPL x402 V2 policy checks.
10
+ - `src/assets.ts` — verified XRPL mainnet XRP / Ripple RLUSD / Circle USDC identity constants and three-asset policy builder.
11
+ - `src/index.ts` — adapter to the existing proven `@x402/core`, `@x402/fetch`, `@x402/xrpl` client.
12
+ - `examples/feral-agent.example.ts` — signer-injection example; no secrets or hardcoded wallet provider.
13
+ - `examples/simulation-only.mjs` — no-wallet, no-network, no-payment demonstration.
14
+ - `tests/policy.test.mjs` and `tests/three-assets.test.mjs` — locally executable approval/denial tests for all three assets.
15
+
16
+ ## On your Mac (do not deploy yet)
17
+
18
+ **Keep this a separate test folder, do not copy over `src/cloudpayx_x402_pay.ts` or `src/cloudpayx_x402_pay_configured.ts`.**
19
+
20
+ 1. Unzip, open Terminal in the unzipped directory.
21
+ 2. Run `npm install` (the official `@x402/*` packages are required for the SDK adapter).
22
+ 3. Run `npm run test:policy` and `npm run demo:dry-run`.
23
+ 4. Run `npm run build` to check SDK integration types against the actual installed packages.
24
+
25
+ `npm run test:policy` needs only the TypeScript compiler, Node.js, and the dependency-free policy module. The build needs official x402 packages; network/package installation was unavailable during packaging.
26
+
27
+ ## Three verified XRPL mainnet assets
28
+
29
+ The optional helper `createThreeAssetPolicy` pins the network to `xrpl:0` and enables ONLY these official asset identities:
30
+
31
+ | Asset | x402 `asset` | x402 `extra.issuer` | Max amount unit |
32
+ | --- | --- | --- | --- |
33
+ | XRP | `XRP` | None | Integer drops (1 XRP = 1,000,000 drops) |
34
+ | Ripple RLUSD | `524C555344000000000000000000000000000000` | `rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De` | Decimal RLUSD tokens |
35
+ | Circle USDC on XRPL | `5553444300000000000000000000000000000000` | `rGm7WCVp9gb4jZHWTEtGUr4dd74z2XuWhE` | Decimal USDC tokens |
36
+
37
+ Only these XRPL issuances are accepted by this helper, *not* similarly named bridged tokens, Base USDC, or arbitrary USD IOUs. Signing always uses a caller-supplied `ClientXrplSigner`. **There is no automatic token conversion, exchange quoting, currency netting, or account registration.**
38
+
39
+ ## Sample: permissionless, self-funded agent using all three
40
+
41
+ ```ts
42
+ import { createCpXX402AgentPay, createThreeAssetPolicy } from './src/index.js';
43
+
44
+ const { paidFetch } = createCpXX402AgentPay({
45
+ signer: MY_SECURE_XRPL_SIGNER, // compatible @x402/xrpl ClientXrplSigner
46
+ policy: createThreeAssetPolicy({
47
+ limits: {
48
+ xrpDrops: '50000', // 0.05 XRP
49
+ rlusd: '0.05', // 0.05 RLUSD
50
+ usdc: '0.05' // 0.05 Circle USDC (XRPL)
51
+ },
52
+ recipients: { mode: 'any' }, // opt-in open seller participation
53
+ approval: { mode: 'autonomous' } // explicit local operator/agent opt-in
54
+ })
55
+ });
56
+ const response = await paidFetch('https://a-trusted-x402-resource.example/report');
57
+ ```
58
+
59
+ `MY_SECURE_XRPL_SIGNER` and seller URL are placeholders. Don't paste wallet secrets into this file. **An unknown agent can use the SDK with its own signer, but does not gain authority over anyone else's funds.**
60
+
61
+ `npm run demo:dry-run` simulates XRP, RLUSD, and USDC policy decisions without a wallet or network.
62
+
63
+ ## Units are not interchangeable
64
+
65
+ | XRPL asset | x402 `amount` units | `maxAmount...` example |
66
+ | --- | --- | --- |
67
+ | Native XRP | Drops (1,000,000 drops = 1 XRP) | `{kind:'xrp',asset:'XRP',maxAmountDrops:'50000'}` = 0.05 XRP |
68
+ | RLUSD, USDC or other XRPL-issued token | Decimal issued-token value | `{kind:'issued', asset:'...', issuer:'...', maxAmount:'0.05'}` = 0.05 token |
69
+
70
+ This module rejects scientific notation and prices above its exact cap. Limits are independent; they are **not** an equivalent USD portfolio budget. **Network fees are extra; the per-payment cap bounds the x402 transfer amount, not the combined cost including XRPL fees, trustline reserves, or issuer transfer fees.** XRPL recipient validation here only checks basic address *shape*. The underlying SDK/signer/facilitator must validate destination checksum, invoice/transaction binding, signature authorization, settlement, and errors.
71
+
72
+ ## Security boundaries
73
+
74
+ - No Xaman dependency and no human cloudpayX account required for self-funded agents.
75
+ - Strict XRPL mainnet `xrpl:0`, x402 V2, `exact` scheme, `areFeesSponsored=false`.
76
+ - Explicit assets and exact amount caps; opt-in seller-neutral recipient policy or allowlist.
77
+ - Explicit `autonomous` opt-in or application-provided authorization callback, with fail-closed exceptions.
78
+ - A self-funded agent retains *unrestricted authority over its own signer*. A local SDK is **not a trust boundary** against an agent holding the key: it can bypass these checks. Hardware signers, dedicated wallets, and controlled signer services are needed for stronger enforcement.
79
+ - **Security protections:** Spending budgets, duplicate-payment protection, resource-host validation, anti-SSRF controls, replay protection, fee budgeting, guarded signing, and validated-ledger reconciliation are covered by the SDK's security tests. These controls apply when payments use the guarded SDK interface.
80
+ - The live x402 facilitator/service should validate transaction signatures and bind invoice, amount, asset, destination and network, as described in the XRPL exact scheme spec.
81
+
82
+ ## Operational conditions for USDC and RLUSD
83
+
84
+ The agent wallet must have the required XRPL token trustline/balance/authorization (where applicable) and enough XRP for transaction fees and reserves. A valid policy decision **does not** guarantee a successful token payment or a resource response. The resource server must advertise a compatible x402 `accepts` entry; the SDK does not auto-swap XRP into stablecoins.
85
+
86
+ XRPL-issued assets require sufficient balances, applicable trustlines, and XRP for fees and reserves. Payment success and resource delivery depend on the network and seller. An agent with unrestricted access to its own signing keys can bypass local SDK policies.
87
+
88
+ **Official issuers:** [Ripple RLUSD](https://docs.ripple.com/products/stablecoin/developer-resources/rlusd-on-the-xrpl) and [Circle XRPL USDC](https://www.circle.com/blog/now-available-usdc-on-the-xrpl).
89
+
90
+ ## Integration guidance
91
+
92
+ Use a dedicated, limited-balance XRPL wallet when integrating a new signer or seller. Validate the complete payment and resource-delivery flow before granting unattended spending authority. For stronger enforcement, keep signing authority outside the agent's direct control.
93
+
94
+ Specifications: https://github.com/x402-foundation/x402/blob/main/specs/schemes/exact/scheme_exact_xrpl.md
package/README.md CHANGED
@@ -1,94 +1,89 @@
1
- # cpX x402 Pay — XRP + RLUSD + USDC XRPL agent SDK (Alpha)
1
+ # cpX x402 Pay
2
2
 
3
- **Purpose:** Let an unaffiliated, self-funded agent participate in the XRPL x402 economy without a cloudpayX registration, dashboard, Supabase session, or required wallet brand. This is a *local client integration* for buying x402 resources, **not** a publicly deployed service, published npm package, or operator-funded wallet gateway.
3
+ **XRPL-native x402 payments for autonomous AI agents.**
4
4
 
5
- This package is **pre-release security work**. It does not authenticate an operator, implement managed mandates, custody funds, create wallets, enforce global daily budgets, or provide guaranteed purchase idempotency. It has not yet been tested end-to-end with a third-party wallet/signer or a live 402 seller. **Do not give it unattended signing access to a valuable wallet.**
5
+ cpX x402 Pay enables autonomous AI agents to purchase x402-protected services using XRP, RLUSD, and Circle USDC on the XRP Ledger.
6
6
 
7
- ## Source
7
+ The SDK provides wallet-agnostic signing integration, explicit payment authorization, spending controls, guarded transactions, persistent payment tracking, and validated-ledger settlement reconciliation.
8
8
 
9
- - `src/policy.ts` — strict, dependency-free XRPL x402 V2 policy checks.
10
- - `src/assets.ts` — verified XRPL mainnet XRP / Ripple RLUSD / Circle USDC identity constants and three-asset policy builder.
11
- - `src/index.ts` — adapter to the existing proven `@x402/core`, `@x402/fetch`, `@x402/xrpl` client.
12
- - `examples/feral-agent.example.ts` — signer-injection example; no secrets or hardcoded wallet provider.
13
- - `examples/simulation-only.mjs` — no-wallet, no-network, no-payment demonstration.
14
- - `tests/policy.test.mjs` and `tests/three-assets.test.mjs` — locally executable approval/denial tests for all three assets.
9
+ Self-funded agents can integrate without a cloudpayX account, dashboard, or mandatory wallet provider.
15
10
 
16
- ## On your Mac (do not deploy yet)
11
+ ## Installation
17
12
 
18
- **Keep this a separate test folder, do not copy over `src/cloudpayx_x402_pay.ts` or `src/cloudpayx_x402_pay_configured.ts`.**
13
+ `npm install @cloudpayx/x402-pay`
19
14
 
20
- 1. Unzip, open Terminal in the unzipped directory.
21
- 2. Run `npm install` (the official `@x402/*` packages are required for the SDK adapter).
22
- 3. Run `npm run test:policy` and `npm run demo:dry-run`.
23
- 4. Run `npm run build` to check SDK integration types against the actual installed packages.
15
+ **Network:** XRPL mainnet (`xrpl:0`)
16
+ **Protocol:** x402 V2, `exact`
17
+ **Assets:** XRP, RLUSD, Circle USDC
24
18
 
25
- `npm run test:policy` needs only the TypeScript compiler, Node.js, and the dependency-free policy module. The build needs official x402 packages; network/package installation was unavailable during packaging.
19
+ ## Capabilities
26
20
 
27
- ## Three verified XRPL mainnet assets
21
+ - **Autonomous agent payments:** Agents can purchase compatible x402 resources using their own XRPL signing infrastructure.
22
+ - **Wallet-agnostic integration:** No mandatory wallet brand or cloudpayX custody.
23
+ - **Three-asset support:** Native XRP, Ripple-issued RLUSD, and Circle-issued USDC with issuer validation.
24
+ - **Payment authorization:** Explicit autonomous opt-in or application-controlled approval.
25
+ - **Spending controls:** Per-asset limits, persistent aggregate budgets, recipient restrictions, and transaction fee ceilings.
26
+ - **Guarded signing:** Checks transaction destination, asset, amount, invoice binding, fees, and other transaction constraints.
27
+ - **Durable payment records:** Persistent journals and duplicate-payment protections.
28
+ - **Settlement verification:** Reconciliation against validated XRPL transaction evidence.
29
+ - **Protected resource access:** HTTPS validation, anti-SSRF protections, and redirect restrictions.
28
30
 
29
- The optional helper `createThreeAssetPolicy` pins the network to `xrpl:0` and enables ONLY these official asset identities:
31
+ ## Public SDK API
30
32
 
31
- | Asset | x402 `asset` | x402 `extra.issuer` | Max amount unit |
32
- | --- | --- | --- | --- |
33
- | XRP | `XRP` | None | Integer drops (1 XRP = 1,000,000 drops) |
34
- | Ripple RLUSD | `524C555344000000000000000000000000000000` | `rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De` | Decimal RLUSD tokens |
35
- | Circle USDC on XRPL | `5553444300000000000000000000000000000000` | `rGm7WCVp9gb4jZHWTEtGUr4dd74z2XuWhE` | Decimal USDC tokens |
33
+ Import the guarded payment operations from `@cloudpayx/x402-pay`.
36
34
 
37
- Only these XRPL issuances are accepted by this helper, *not* similarly named bridged tokens, Base USDC, or arbitrary USD IOUs. Signing always uses a caller-supplied `ClientXrplSigner`. **There is no automatic token conversion, exchange quoting, currency netting, or account registration.**
35
+ | Export | Purpose |
36
+ | --- | --- |
37
+ | `validateSecureNodePurchase` | Validate a proposed guarded payment configuration. |
38
+ | `executeSecureNodePurchase` | Execute a policy-controlled XRPL x402 purchase. |
39
+ | `reconcileSecureNodePurchase` | Reconcile an existing purchase against validated XRPL ledger evidence. |
38
40
 
39
- ## Sample: permissionless, self-funded agent using all three
41
+ Payment execution requires compatible signing infrastructure and application-supplied authorization and policy configuration.
40
42
 
41
- ```ts
42
- import { createCpXX402AgentPay, createThreeAssetPolicy } from './src/index.js';
43
+ ## Supported assets
43
44
 
44
- const { paidFetch } = createCpXX402AgentPay({
45
- signer: MY_SECURE_XRPL_SIGNER, // compatible @x402/xrpl ClientXrplSigner
46
- policy: createThreeAssetPolicy({
47
- limits: {
48
- xrpDrops: '50000', // 0.05 XRP
49
- rlusd: '0.05', // 0.05 RLUSD
50
- usdc: '0.05' // 0.05 Circle USDC (XRPL)
51
- },
52
- recipients: { mode: 'any' }, // opt-in open seller participation
53
- approval: { mode: 'autonomous' } // explicit local operator/agent opt-in
54
- })
55
- });
56
- const response = await paidFetch('https://a-trusted-x402-resource.example/report');
57
- ```
45
+ | Asset | Network | Amount format |
46
+ | --- | --- | --- |
47
+ | XRP | XRPL mainnet | Integer drops |
48
+ | RLUSD | XRPL mainnet | Decimal token amounts, Ripple issuer-bound |
49
+ | Circle USDC | XRPL mainnet | Decimal token amounts, Circle issuer-bound |
58
50
 
59
- `MY_SECURE_XRPL_SIGNER` and seller URL are placeholders. Don't paste wallet secrets into this file. **An unknown agent can use the SDK with its own signer, but does not gain authority over anyone else's funds.**
51
+ **cpX x402 Pay is XRPL-only.** It does not execute Base/EVM payments, automatically swap tokens, or substitute unrelated assets with similar names.
60
52
 
61
- `npm run demo:dry-run` simulates XRP, RLUSD, and USDC policy decisions without a wallet or network.
53
+ ## Payment lifecycle
62
54
 
63
- ## Units are not interchangeable
55
+ 1. An agent requests an x402-protected resource.
56
+ 2. The resource returns payment requirements.
57
+ 3. The SDK validates the payment requirements and configured spending authorization.
58
+ 4. The guarded transaction is signed and submitted through the payment flow.
59
+ 5. Purchase state and transaction evidence are preserved.
60
+ 6. Ledger reconciliation verifies the settlement outcome.
64
61
 
65
- | XRPL asset | x402 `amount` units | `maxAmount...` example |
66
- | --- | --- | --- |
67
- | Native XRP | Drops (1,000,000 drops = 1 XRP) | `{kind:'xrp',asset:'XRP',maxAmountDrops:'50000'}` = 0.05 XRP |
68
- | RLUSD, USDC or other XRPL-issued token | Decimal issued-token value | `{kind:'issued', asset:'...', issuer:'...', maxAmount:'0.05'}` = 0.05 token |
62
+ Uncertain payment results require reconciliation rather than automatic duplicate payment attempts.
63
+
64
+ ## Security architecture
69
65
 
70
- This module rejects scientific notation and prices above its exact cap. Limits are independent; they are **not** an equivalent USD portfolio budget. **Network fees are extra; the per-payment cap bounds the x402 transfer amount, not the combined cost including XRPL fees, trustline reserves, or issuer transfer fees.** XRPL recipient validation here only checks basic address *shape*. The underlying SDK/signer/facilitator must validate destination checksum, invoice/transaction binding, signature authorization, settlement, and errors.
66
+ The guarded SDK interface incorporates explicit authorization, spending budgets, transaction-signing restrictions, invoice binding, issuer validation, fee controls, duplicate-payment protection, safe resource-host validation, and ledger reconciliation.
71
67
 
72
- ## Security boundaries
68
+ Applications must secure their XRPL signing credentials independently. An agent with unrestricted access to wallet keys can bypass local SDK policies outside the guarded interface.
73
69
 
74
- - No Xaman dependency and no human cloudpayX account required for self-funded agents.
75
- - Strict XRPL mainnet `xrpl:0`, x402 V2, `exact` scheme, `areFeesSponsored=false`.
76
- - Explicit assets and exact amount caps; opt-in seller-neutral recipient policy or allowlist.
77
- - Explicit `autonomous` opt-in or application-provided authorization callback, with fail-closed exceptions.
78
- - A self-funded agent retains *unrestricted authority over its own signer*. A local SDK is **not a trust boundary** against an agent holding the key: it can bypass these checks. Hardware signers, dedicated wallets, and controlled signer services are needed for stronger enforcement.
79
- - **Not yet solved:** daily budgets; concurrent duplicate payments; resource-host validation, anti-SSRF, payment replays; wallet cross-network replay risks; fee caps; seller fraud; external signing adapters; end-to-end validated settlement checks; managed/delegated spending and revocation. The XRPL scheme uses account sequence/tickets; concurrent sequence-method payments require coordination.
80
- - The live x402 facilitator/service should validate transaction signatures and bind invoice, amount, asset, destination and network, as described in the XRPL exact scheme spec.
70
+ Issued-token payments require applicable trustlines, sufficient balances, and XRP for network fees and reserves. Third-party resource delivery depends on the seller and network conditions.
81
71
 
82
- ## Operational conditions for USDC and RLUSD
72
+ ## Testing
83
73
 
84
- The agent wallet must have the required XRPL token trustline/balance/authorization (where applicable) and enough XRP for transaction fees and reserves. A valid policy decision **does not** guarantee a successful token payment or a resource response. The resource server must advertise a compatible x402 `accepts` entry; the SDK does not auto-swap XRP into stablecoins.
74
+ The v0.2.2 implementation completed:
85
75
 
86
- The underlying XRPL exact scheme includes issuer binding and fee-payment rules. The current Alpha does not make independent fee ceilings, balance checks, trustline checks, daily budgets, concurrency locks, or validated settlement guarantees. A self-funded agent holding its own signing authority can bypass an SDK policy. **Do not enable unattended real-money signing until those boundaries are addressed.**
76
+ - **234 automated tests passed**
77
+ - **0 test failures**
78
+ - **Successful TypeScript build**
87
79
 
88
- **Official issuers:** [Ripple RLUSD](https://docs.ripple.com/products/stablecoin/developer-resources/rlusd-on-the-xrpl) and [Circle XRPL USDC](https://www.circle.com/blog/now-available-usdc-on-the-xrpl).
80
+ Test coverage includes supported assets, authorization, guarded signing, persistent budgets, transaction journaling, HTTP resource protections, and settlement reconciliation.
89
81
 
90
- ## Next milestone
82
+ ## Resources
91
83
 
92
- Use a **dedicated funded test wallet** and a real compatible XRPL x402 resource in a supervised, deliberately low-value interoperability test. First reconcile Node/Bun and dependency-compatibility, then add durable budget reservation and signing isolation for *operator-funded* agents. Do not enable real-money unattended signing on this Alpha example.
84
+ - Website: https://cloudpayx.com
85
+ - Agent infrastructure: https://api.cloudpayxagent.xyz
86
+ - npm: https://www.npmjs.com/package/@cloudpayx/x402-pay
87
+ - XRPL x402 specification: https://github.com/x402-foundation/x402/blob/main/specs/schemes/exact/scheme_exact_xrpl.md
93
88
 
94
- Specifications: https://github.com/x402-foundation/x402/blob/main/specs/schemes/exact/scheme_exact_xrpl.md
89
+ **cloudpayX | Infrastructure for the autonomous economy**
package/package.json CHANGED
@@ -1,9 +1,8 @@
1
1
  {
2
2
  "name": "@cloudpayx/x402-pay",
3
- "version": "0.2.1",
4
- "private": false,
3
+ "version": "0.2.3",
5
4
  "type": "module",
6
- "description": "Experimental, wallet-agnostic, account-free XRP, RLUSD and USDC XRPL x402 buyer integration",
5
+ "description": "XRPL-native x402 payment SDK for autonomous AI agents. Secure, wallet-agnostic XRP, RLUSD and Circle USDC payments with spending policies and verified settlement.",
7
6
  "dependencies": {
8
7
  "@x402/core": "2.28.0",
9
8
  "@x402/fetch": "2.28.0",
@@ -40,8 +39,5 @@
40
39
  "scripts/trusted-xrpl-recovery.mjs",
41
40
  "types/",
42
41
  "README.md"
43
- ],
44
- "publishConfig": {
45
- "access": "public"
46
- }
42
+ ]
47
43
  }