@paystage/x-evm 0.0.0-stage → 0.1.1

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 +47 -2
  2. package/package.json +49 -4
package/README.md CHANGED
@@ -1,3 +1,48 @@
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 with batching schemes too
33
+
34
+ `@circle-fin/x402-batching`'s `BatchEvmScheme` exposes `createPaymentPayload` like every other scheme,
35
+ plus batching hooks. The guard wraps only that one method, so the hooks are untouched and a guarded
36
+ batched payment is evaluated exactly like a single one. There is no separate batching package because
37
+ none is needed — there is a test that proves the hooks survive.
38
+
39
+ ## What it does not do
40
+
41
+ No network calls, no keys, no signing of its own. It evaluates the requirements you were already
42
+ given and either lets the scheme proceed or refuses. Evaluation is local and synchronous in effect.
43
+
44
+ ## Tests
45
+
46
+ Seven, and the ones that matter count signatures: a refused payment must leave `created === 0`.
47
+
48
+ 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",
4
+ "description": "PayStage guard for @x402/evm \u2014 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",
45
+ "@paystage/policy": "0.2.1"
46
+ },
47
+ "devDependencies": {
48
+ "typescript": "^5.9.3",
49
+ "vitest": "^4.1.12"
50
+ }
51
+ }