@paystage/x-evm 0.0.0-stage → 0.1.1-canary.22

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 (2) hide show
  1. package/README.md +54 -2
  2. package/package.json +49 -4
package/README.md CHANGED
@@ -1,3 +1,55 @@
1
- # Temporary Holding Version
1
+ # @paystage/x-evm
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Guard for [`@x402/evm`](https://www.npmjs.com/package/@x402/evm): evaluate the payment requirements
4
+ **before** the EVM scheme signs.
5
+
6
+ ```bash
7
+ npm i @paystage/x-evm
8
+ ```
9
+
10
+ ```ts
11
+ import { ExactEvmScheme } from "@x402/evm/exact/client";
12
+ import { guardScheme } from "@paystage/x-evm";
13
+
14
+ const scheme = guardScheme(new ExactEvmScheme(signer), { policy });
15
+ // createPaymentPayload now throws instead of signing a payment the policy refuses
16
+ ```
17
+
18
+ ## Why this exists
19
+
20
+ `@x402/evm` does one thing well: it builds and signs the payload. That is exactly why a policy cannot
21
+ live there — by the time `createPaymentPayload` runs, the decision to sign has already been made.
22
+
23
+ `createPaymentPayload()` is the single choke point every scheme variant shares, so one wrapper covers
24
+ `ExactEvmScheme`, `UptoEvmScheme`, `BatchSettlementEvmScheme` and anything else inheriting it.
25
+
26
+ ## A refusal throws
27
+
28
+ Not a return value. A caller that ignores a return value would sign anyway, and the point is that it
29
+ cannot. Catch `PaymentRefusedError` and read `.verdict.reasons` — the sentences name what failed, so
30
+ they can be pasted into a policy fix.
31
+
32
+ ## Works across chains, not just EVM
33
+
34
+ The name says EVM but the guard wraps `createPaymentPayload`, which every x402 client scheme exposes —
35
+ `@x402/svm`'s `ExactSvmScheme`, `UptoSvmScheme` and `BatchSvmScheme` included. A Solana payment is
36
+ evaluated by the same policy; `allowed_networks` is what decides, so an `eip155:`-only policy refuses
37
+ it with a reason rather than signing it.
38
+
39
+ ## Works with batching schemes too
40
+
41
+ `@circle-fin/x402-batching`'s `BatchEvmScheme` exposes `createPaymentPayload` like every other scheme,
42
+ plus batching hooks. The guard wraps only that one method, so the hooks are untouched and a guarded
43
+ batched payment is evaluated exactly like a single one. There is no separate batching package because
44
+ none is needed — there is a test that proves the hooks survive.
45
+
46
+ ## What it does not do
47
+
48
+ No network calls, no keys, no signing of its own. It evaluates the requirements you were already
49
+ given and either lets the scheme proceed or refuses. Evaluation is local and synchronous in effect.
50
+
51
+ ## Tests
52
+
53
+ Seven, and the ones that matter count signatures: a refused payment must leave `created === 0`.
54
+
55
+ MIT.
package/package.json CHANGED
@@ -1,6 +1,51 @@
1
1
  {
2
2
  "name": "@paystage/x-evm",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.1-canary.22",
4
+ "description": "PayStage guard for @x402/evm — evaluate the payment requirements before the EVM scheme signs",
5
+ "license": "MIT",
6
+ "type": "module",
7
+ "main": "./dist/index.js",
8
+ "types": "./dist/index.d.ts",
9
+ "exports": {
10
+ ".": {
11
+ "types": "./dist/index.d.ts",
12
+ "import": "./dist/index.js"
13
+ }
14
+ },
15
+ "files": [
16
+ "dist",
17
+ "README.md"
18
+ ],
19
+ "repository": {
20
+ "type": "git",
21
+ "url": "git+https://github.com/base-buzz/paystage.git",
22
+ "directory": "packages/x-evm"
23
+ },
24
+ "keywords": [
25
+ "x402",
26
+ "evm",
27
+ "agent-payments",
28
+ "preflight",
29
+ "guard"
30
+ ],
31
+ "scripts": {
32
+ "build": "tsc -p tsconfig.json",
33
+ "test": "vitest run"
34
+ },
35
+ "peerDependencies": {
36
+ "@x402/evm": ">=2.29.0"
37
+ },
38
+ "peerDependenciesMeta": {
39
+ "@x402/evm": {
40
+ "optional": true
41
+ }
42
+ },
43
+ "dependencies": {
44
+ "@paystage/preflight": "0.2.3-canary.22",
45
+ "@paystage/policy": "0.2.1-canary.22"
46
+ },
47
+ "devDependencies": {
48
+ "typescript": "^5.9.3",
49
+ "vitest": "^4.1.12"
50
+ }
51
+ }