@gblin-protocol/mcp-server 0.4.3 → 0.5.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 (63) hide show
  1. package/AGENTS.md +49 -20
  2. package/README.md +111 -11
  3. package/dist/abi.d.ts +27 -0
  4. package/dist/abi.d.ts.map +1 -1
  5. package/dist/abi.js +1 -0
  6. package/dist/abi.js.map +1 -1
  7. package/dist/actions.d.ts +306 -0
  8. package/dist/actions.d.ts.map +1 -0
  9. package/dist/actions.js +749 -0
  10. package/dist/actions.js.map +1 -0
  11. package/dist/auction.d.ts.map +1 -1
  12. package/dist/auction.js +5 -4
  13. package/dist/auction.js.map +1 -1
  14. package/dist/config.d.ts +20 -3
  15. package/dist/config.d.ts.map +1 -1
  16. package/dist/config.js +23 -6
  17. package/dist/config.js.map +1 -1
  18. package/dist/helpers.d.ts +6 -0
  19. package/dist/helpers.d.ts.map +1 -1
  20. package/dist/helpers.js +37 -13
  21. package/dist/helpers.js.map +1 -1
  22. package/dist/index.d.ts +3 -4
  23. package/dist/index.d.ts.map +1 -1
  24. package/dist/index.js +38 -19
  25. package/dist/index.js.map +1 -1
  26. package/dist/output-schemas.d.ts +18 -0
  27. package/dist/output-schemas.d.ts.map +1 -0
  28. package/dist/output-schemas.js +243 -0
  29. package/dist/output-schemas.js.map +1 -0
  30. package/dist/payments.d.ts +170 -0
  31. package/dist/payments.d.ts.map +1 -0
  32. package/dist/payments.js +524 -0
  33. package/dist/payments.js.map +1 -0
  34. package/dist/paywall.d.ts +10 -1
  35. package/dist/paywall.d.ts.map +1 -1
  36. package/dist/paywall.js +1 -1
  37. package/dist/paywall.js.map +1 -1
  38. package/dist/prompts.d.ts +33 -0
  39. package/dist/prompts.d.ts.map +1 -0
  40. package/dist/prompts.js +139 -0
  41. package/dist/prompts.js.map +1 -0
  42. package/dist/receipts.d.ts +2 -1
  43. package/dist/receipts.d.ts.map +1 -1
  44. package/dist/receipts.js +16 -12
  45. package/dist/receipts.js.map +1 -1
  46. package/dist/resources.d.ts +17 -0
  47. package/dist/resources.d.ts.map +1 -0
  48. package/dist/resources.js +146 -0
  49. package/dist/resources.js.map +1 -0
  50. package/dist/shared.d.ts +35 -0
  51. package/dist/shared.d.ts.map +1 -0
  52. package/dist/shared.js +68 -0
  53. package/dist/shared.js.map +1 -0
  54. package/dist/tools.d.ts +106 -19
  55. package/dist/tools.d.ts.map +1 -1
  56. package/dist/tools.js +124 -117
  57. package/dist/tools.js.map +1 -1
  58. package/dist/version.d.ts +2 -0
  59. package/dist/version.d.ts.map +1 -0
  60. package/dist/version.js +3 -0
  61. package/dist/version.js.map +1 -0
  62. package/llms.txt +24 -2
  63. package/package.json +8 -3
package/AGENTS.md CHANGED
@@ -10,7 +10,7 @@
10
10
  ## What this repo is
11
11
 
12
12
  `@gblin-protocol/mcp-server` is the official **Model Context Protocol** server
13
- for the GBLIN protocol on Base mainnet. It exposes 13 tools that let any AI
13
+ for the GBLIN protocol on Base mainnet. It exposes twenty tools that let any AI
14
14
  agent read live treasury state, verify governance and attestations, and
15
15
  produce ready-to-broadcast calldata to enter, leave and bid.
16
16
 
@@ -35,9 +35,11 @@ swap) that lets agents convert GBLIN to USDC the moment an x402 invoice arrives.
35
35
  2. **Never accept `minOut = 0`.** Every swap quote must produce a strictly
36
36
  positive `minOut` derived from the Lens (`quoteSell` / `quoteBuy`)
37
37
  plus a dynamic slippage buffer (2.5 % normal / 4 % during Crash Shield).
38
- 3. **Stale-feed guard.** Reject any Chainlink ETH/USD answer older than 24 h
39
- or non-positive. Tools must abort with a clear error rather than return
40
- bad data.
38
+ 3. **Stale-feed guard.** Reject any Chainlink answer that is non-positive or
39
+ older than the vault accepts: 26 hours for a stable asset's feed, the
40
+ vault's own `oracleAge` (read live through the Lens) for every other. The
41
+ server never quotes on a price the contract would refuse; tools abort with
42
+ a clear error rather than return bad data.
41
43
  4. **No new RPC endpoints.** Stick to Base mainnet via the user-supplied
42
44
  `GBLIN_RPC_URL` env var (defaults to `https://base-rpc.publicnode.com`).
43
45
  5. **No emoji in code or commits** unless the user explicitly asks.
@@ -50,8 +52,15 @@ swap) that lets agents convert GBLIN to USDC the moment an x402 invoice arrives.
50
52
 
51
53
  | Path | Purpose |
52
54
  | --- | --- |
53
- | `src/index.ts` | MCP server entry — registers the 10 tools |
54
- | `src/tools.ts` | All tool definitions + handlers (treasury, quote, JIT, invest, health, governance, keeper, risk, share, verify) |
55
+ | `src/index.ts` | MCP server entry — registers tools, prompts and resources, and the instructions sent at initialize |
56
+ | `src/tools.ts` | Tool definitions and handlers (treasury, quote, JIT, invest, health, governance, auction, risk, share, verify) |
57
+ | `src/payments.ts` | Gasless GBLIN payments (EIP-3009): prepare, verify and relay an authorization |
58
+ | `src/actions.ts` | prepare_action, preview_steps, get_transaction_status, get_nav_history |
59
+ | `src/shared.ts` | Result envelopes, builder code, Zap routing data and gas limit |
60
+ | `src/receipts.ts` | AI Action Receipts: demo seal, receipt read, paid-seal instructions |
61
+ | `src/auction.ts` | Reads the rebalancing auction through the Lens |
62
+ | `src/output-schemas.ts` | The `outputSchema` of every tool: the fields a successful result always carries |
63
+ | `src/prompts.ts` / `src/resources.ts` | MCP prompts (workflows) and resources (reference data) |
55
64
  | `src/client.ts` / `src/abi.ts` / `src/helpers.ts` | viem client, ABI fragments, NAV math, slippage |
56
65
  | `server.json` | MCP registry manifest (do not bump version casually) |
57
66
  | `llms.txt` | Crawler-friendly index used by AI tooling discovery |
@@ -60,9 +69,14 @@ swap) that lets agents convert GBLIN to USDC the moment an x402 invoice arrives.
60
69
 
61
70
  ```bash
62
71
  npm install
63
- npm run build # tsc; must pass
64
- npm test # if tests exist for the tool you touched
65
- npm run prepublish # bumps dist/, runs build, lints package.json
72
+ npm run build # tsc; must pass
73
+ npm test # handler tests against Base mainnet (read-only)
74
+ npm run test:protocol # speaks MCP over stdio: capabilities, prompts, resources
75
+ npm run test:schemas # every tool through the official MCP client, validating outputSchema
76
+ # On a fork of Base (anvil --fork-url <rpc> --port 8555), with GBLIN_RPC_URL=http://127.0.0.1:8555:
77
+ npm run test:payments # gasless payment: sign, verify, carry, replay and front-run refused
78
+ npm run test:calldata # sends the JIT exit and the investment steps exactly as returned
79
+ npm run test:actions # every prepare_action: simulated, sent, read back; gas limits by bisection
66
80
  ```
67
81
 
68
82
  Releases are manual: `npm version patch && npm publish --access public`.
@@ -96,22 +110,36 @@ if usdc_balance > 7 * daily_burn_usd AND no_pending_x402_invoice:
96
110
  call invest_usdc_to_gblin (park SURPLUS USDC — keep operating cash in USDC)
97
111
 
98
112
  if x402_invoice_arrives AND usdc_balance < invoice_amount:
99
- call swap_gblin_to_usdc_jit (one atomic tx → enough USDC to pay)
113
+ call swap_gblin_to_usdc_jit (three transactions, batchable → enough USDC to pay)
100
114
  ```
101
115
 
102
- ### The 10 tools
116
+ ### The twenty tools
103
117
 
104
118
  | Tool | Use it when |
105
119
  | --- | --- |
106
- | `get_market_risk_regime` | Before any risk decision — BTC/ETH regime + posture ($0.002) |
107
- | `verify_risk_attestation` | Verify a peer's Risk Attestation before trusting it (free) |
108
- | `get_treasury_state` | Read live NAV, basket weights, Crash Shield status |
109
- | `quote_safe_swap` | Preview a buy/sell with MEV-safe `minOut` |
110
- | `swap_gblin_to_usdc_jit` | Pay an x402 invoice — atomic GBLIN→USDC swap |
111
- | `invest_usdc_to_gblin` | Convert agent earnings (USDC) back into GBLIN |
112
- | `analyze_treasury_health` | Full balance, gas runway, rebalance hint |
113
- | `get_governance_state` | Owner, pending owner, timelock roles and scheduled operations |
120
+ | `get_market_risk_regime` | Before any risk decision: calm, elevated or crash, read on chain |
121
+ | `verify_risk_attestation` | Verify a peer's signed risk attestation before trusting it |
122
+ | `get_treasury_state` | Read live NAV, basket weights, fees and crash-shield status |
123
+ | `quote_safe_swap` | Preview a mint with ETH or an exit to ETH, with a safe minimum out |
124
+ | `swap_gblin_to_usdc_jit` | Pay an invoice: exit GBLIN to exactly the USDC needed |
125
+ | `invest_usdc_to_gblin` | Park surplus USDC in GBLIN |
126
+ | `analyze_treasury_health` | Balances, gas runway, cooldown and a rebalance hint |
127
+ | `get_governance_state` | Owner, timelock, pending handover and scheduled operations |
114
128
  | `get_auction_state` | The rebalancing auction: side, gap and premium per row, with the bid |
129
+ | `prepare_action` | Prepare any operation: mint with ETH, WETH or USDC, redeem in kind, exit to ETH or USDC, bid |
130
+ | `preview_steps` | Before signing: simulate the steps and get the gas each vault step really needs |
131
+ | `get_transaction_status` | After sending: what the transaction did |
132
+ | `get_nav_history` | How the NAV moved over time, beside ETH and BTC |
133
+ | `prepare_gblin_payment` | Build a gasless GBLIN payment: EIP-712 message, calldata and x402 payload |
134
+ | `relay_gblin_payment` | When nobody else will carry the payment: GBLIN's relay settles it, fee in GBLIN |
135
+ | `verify_gblin_authorization` | Check a signed authorization against the chain before spending gas |
136
+ | `share_skill_with_peer` | Hand another agent a ready-to-install description of this server |
137
+ | `seal_action_demo` | Seal the hashes of an action into the public transparency log (5 per day per IP) |
138
+ | `get_receipt` | Read a sealed receipt back, with its inclusion proof |
139
+ | `how_to_seal_paid` | Instructions for paid, unlimited seals over x402 |
140
+
141
+ Every tool is free by default. Every tool but `seal_action_demo` declares an
142
+ `outputSchema`; the four prompts and four resources are listed by the server.
115
143
 
116
144
  ### Anti-patterns to avoid
117
145
 
@@ -120,7 +148,8 @@ if x402_invoice_arrives AND usdc_balance < invoice_amount:
120
148
  - Holding the agent's private key in your server just to perform swaps —
121
149
  this MCP server is **stateless and key-less by design**.
122
150
  - Hard-coding the GBLIN contract address — read it from `get_treasury_state`
123
- so the agent stays correct across upgrades.
151
+ (`meta.vault`) or the `gblin://contracts` resource, so the agent follows a
152
+ redeployment instead of paying into a contract that is no longer in service.
124
153
 
125
154
  ### Resources
126
155
 
package/README.md CHANGED
@@ -19,12 +19,17 @@ Documentation and quick start: [gblin.digital/agents](https://gblin.digital/agen
19
19
 
20
20
  - Market risk regime (`calm` / `elevated` / `crash`) read from the vault's on-chain Crash Shield, with a severity score and a risk posture
21
21
  - Quotes at NAV for minting and redeeming, with a dynamic slippage buffer
22
- - Unsigned calldata to mint with USDC and to exit to USDC just in time for a payment, through the GBLIN Zap
22
+ - One tool that prepares any operation on the vault (mint with ETH, WETH or USDC, redeem in kind, exit to ETH or USDC, bid in the auction), each step with its gas limit
23
+ - Simulation of those steps before signing, in sequence against the latest block, with decoded revert reasons and the gas limit each vault step really needs
24
+ - The outcome of a sent transaction, and the NAV per share over time beside ETH and BTC
23
25
  - Treasury health of an agent wallet: balances, gas runway, cooldown, allocation advice
24
26
  - Governance verification: owner, pending owner, timelock roles and scheduled operations, computed from the chain
25
27
  - The state of the rebalancing auction, row by row, with the bid to send
28
+ - Gasless payments in GBLIN (EIP-3009): prepare the authorization to sign, check it against the chain before anyone spends gas, and, when nobody else will carry it, have GBLIN's relay settle it with the fee in GBLIN, in one atomic transaction
26
29
  - Offline verification of Risk Attestations (EIP-712) and of AI Action Receipts (RFC 6962)
27
30
  - A portable skill seed to onboard a peer agent
31
+ - Four prompts (ready-made workflows) and four resources (deployment, payments, keys, limits)
32
+ - An `outputSchema` on every tool that returns an object, so a client can validate results and generate types
28
33
 
29
34
  Every tool is free. The server never charges: revenue comes from the on-chain protocol fee when an agent actually uses GBLIN. Verifiable pay-per-call lives on the HTTP endpoints listed under [x402 endpoints](#x402-endpoints).
30
35
 
@@ -43,7 +48,7 @@ Fees: 0.10% on every mint with ETH or WETH (0.05% stays in the vault and lifts t
43
48
 
44
49
  ## Hosted variant
45
50
 
46
- A stateless Streamable HTTP server with a smaller tool set runs at `https://gblin-mcp.gblin-mcp-worker.workers.dev/mcp` — no install, no auth, no session, 60 requests per minute per IP. GET-only audit surfaces: [`/meta`](https://gblin-mcp.gblin-mcp-worker.workers.dev/meta), [`/tools.json`](https://gblin-mcp.gblin-mcp-worker.workers.dev/tools.json), [`/resources.json`](https://gblin-mcp.gblin-mcp-worker.workers.dev/resources.json), [`/conformance`](https://gblin-mcp.gblin-mcp-worker.workers.dev/conformance). Also listed on [Smithery](https://smithery.ai/servers/gblin-protocol/mcp).
51
+ A stateless Streamable HTTP server runs at `https://gblin-mcp.gblin-mcp-worker.workers.dev/mcp` — no install, no auth, no session, 60 requests per minute per IP. It serves the vault, action and payment tools of this package under two-level names (`treasury.*`, `actions.*`, `payments.*`, `governance.state`, `auction.state`, `attestation.verify`), built from the same source, plus the risk, receipts and coherence tools; the snake_case names below are accepted there as aliases. GET-only audit surfaces: [`/meta`](https://gblin-mcp.gblin-mcp-worker.workers.dev/meta), [`/tools.json`](https://gblin-mcp.gblin-mcp-worker.workers.dev/tools.json), [`/resources.json`](https://gblin-mcp.gblin-mcp-worker.workers.dev/resources.json), [`/conformance`](https://gblin-mcp.gblin-mcp-worker.workers.dev/conformance). Also listed on [Smithery](https://smithery.ai/servers/gblin-protocol/mcp).
47
52
 
48
53
  ## API
49
54
 
@@ -101,6 +106,57 @@ A stateless Streamable HTTP server with a smaller tool set runs at `https://gbli
101
106
  - Inputs: none
102
107
  - The premium is the whole reward; nothing is paid out of the vault. The input is reduced to what closes the gap
103
108
 
109
+ - **prepare_gblin_payment**
110
+ - Builds a gasless GBLIN payment. The share token implements EIP-3009, the same mechanism USDC uses: the holder signs an authorization and anybody can carry it on chain, so the payer needs no ETH. Returns the EIP-712 message to sign, the amount in shares and atomic units, the payer's balance, the x402 "exact" payload for paying an HTTP endpoint in GBLIN, and the accepts block a seller publishes to be paid in GBLIN
111
+ - Inputs:
112
+ - `from` (string): the payer, the wallet that will sign
113
+ - `to` (string): the recipient
114
+ - `amount_gblin` (string) or `amount_usd` (string): the amount, converted at the live NAV when given in USD
115
+ - `method` (string, optional): `receive` (default) can be submitted only by the recipient, so nobody can front-run it; `transfer` can be submitted by anyone, which is what an x402 facilitator does
116
+ - `valid_for_seconds` (number, optional): default 600, maximum 86,400
117
+ - The EIP-712 domain is read from the token through EIP-5267, never assumed. No private key is requested, held or transmitted
118
+
119
+ - **verify_gblin_authorization**
120
+ - Checks a signed authorization against the chain before anyone spends gas on it: recovers the signer from the digest, or asks the wallet itself through ERC-1271 when the payer is a contract, then checks the validity window against on-chain time, whether the nonce has been used or cancelled, and whether the payer still holds the amount. Returns a verdict, the failing reasons, and the ready calldata when it would settle
121
+ - Inputs:
122
+ - `authorization` (object): from, to, value, validAfter, validBefore, nonce
123
+ - `signature` (string): produced by the payer's wallet
124
+ - `method` (string, optional): `receive` (default) or `transfer`
125
+ - These are the checks an x402 facilitator runs, so a `would_settle` verdict means the payment is good to carry
126
+
127
+ - **relay_gblin_payment**
128
+ - Hands a signed payment and a signed relay fee to GBLIN's relay (`https://gblin.digital/api/relay/gblin`), which checks both against the chain, simulates them and submits them in one transaction through Multicall3: both settle or neither does. For a payer that holds no ETH and has nobody to carry the payment
129
+ - Inputs:
130
+ - `payment` (object): `{ authorization, signature }`, method `transfer`
131
+ - `fee` (object): `{ authorization, signature }` from the `relay` block of `prepare_gblin_payment` called with `relay: true`
132
+ - The fee is quoted live by the relay, in GBLIN at the NAV. This tool moves funds: it is marked destructive so clients ask before running it
133
+
134
+ - **prepare_action**
135
+ - Builds the unsigned steps for any operation on the vault, in order, each through the vault or the Zap carrying its gas limit
136
+ - Inputs:
137
+ - `action` (string): `mint_with_eth`, `mint_with_weth`, `mint_with_usdc`, `redeem_in_kind`, `exit_to_eth`, `exit_to_usdc` or `bid`
138
+ - `wallet_address` (string): the wallet that will sign and receive
139
+ - `amount` (string): in ETH, WETH or USDC for mints, in shares for redemptions and the ETH exit, the USDC needed for the USDC exit; not used by `bid`
140
+ - `row` (integer, optional): `bid` only, the basket row; default the largest gap
141
+ - Returns the steps, what they should deliver with the minimums applied, and warnings such as an active cooldown or an amount above the balance
142
+
143
+ - **preview_steps**
144
+ - Simulates a list of transactions in sequence against the latest block with `eth_simulateV1`, each seeing the state the previous ones left. Returns, per step, success, gas used, whether the given limit is enough, the recommended limit and the decoded revert reason with a hint; and the net token and ETH movements for the wallet
145
+ - Inputs:
146
+ - `from` (string): the wallet that will send the steps
147
+ - `steps` (array): the steps as the tools return them: `target`, `calldata`, optional `value` and `gas`
148
+ - For steps into the vault or the Zap the recommended limit is the smallest one that passes, found by bisection: the vault reserves gas for its capped transfers, so the gas a call uses is below the limit it needs
149
+ - `gas_limit_enough` is `true` when the step passes with the limit it carries, `false` only when that limit is what makes it fail, and `null` when it fails for another reason (a slippage bound, a cooldown), which `error` and `hint` name
150
+
151
+ - **get_transaction_status**
152
+ - What a sent transaction did: pending, success, reverted or not found; block, confirmations, fee, net token movements for the sender, and the decoded reason when it reverted
153
+ - Inputs: `hash` (string)
154
+
155
+ - **get_nav_history**
156
+ - NAV per share over time, read at past blocks, beside the ETH/USD and BTC/USD feeds the vault uses, with the change of each over the window and the NAV's largest drawdown. History starts at the deployment of the vault in service
157
+ - Inputs: `interval` (`hour` or `day`, default `day`), `points` (2 to 90, default 30)
158
+ - Historical reads use public endpoints that serve them; set `GBLIN_ARCHIVE_RPC_URL` to use your own
159
+
104
160
  - **verify_risk_attestation**
105
161
  - Verifies a Risk Attestation offline: recomputes the EIP-712 id, recovers the signer and checks it against the published attestor, checks freshness, and reports the live drift of the regime since issuance
106
162
  - Inputs:
@@ -132,10 +188,34 @@ Every tool sets [MCP tool annotations](https://modelcontextprotocol.io/specifica
132
188
 
133
189
  | Tool | readOnlyHint | idempotentHint | destructiveHint | openWorldHint |
134
190
  |---|---|---|---|---|
135
- | all except `seal_action_demo` | `true` | `true` | `false` | `true` |
191
+ | all except the three below | `true` | `true` | `false` | `true` |
192
+ | `prepare_gblin_payment` | `true` | `false` | `false` | `true` |
136
193
  | `seal_action_demo` | `false` | `false` | `false` | `true` |
194
+ | `relay_gblin_payment` | `false` | `true` | `true` | `true` |
137
195
 
138
- Calldata builders are read-only: they return bytes, they do not send them. Sealing appends to a public log and is never destructive.
196
+ Calldata builders are read-only: they return bytes, they do not send them. `prepare_gblin_payment` is not idempotent because every call draws a fresh nonce. Sealing appends to a public log and is never destructive. `relay_gblin_payment` moves the payer's funds on chain, so it is marked destructive and clients should confirm before calling it. Every tool also carries a human-readable `title`.
197
+
198
+ ### Output schemas
199
+
200
+ Every tool except `seal_action_demo` declares an `outputSchema`. A successful result carries the same object as `structuredContent` and as JSON text. The `required` list of each schema is the contract: fields a successful call always returns. Other fields are described but optional, and the schemas accept additional fields, so adding one is not a breaking change. Errors carry `isError: true` and no structured content.
201
+
202
+ ### Prompts
203
+
204
+ | Prompt | What it does |
205
+ |---|---|
206
+ | `risk_gate` | Reads the regime and applies a rule stated before looking: proceed, halve, or stand down |
207
+ | `pay_in_gblin` | Prepare, sign in the payer's wallet, verify, then hand on a gasless GBLIN payment |
208
+ | `pay_invoice_just_in_time` | Exit just enough GBLIN to USDC to settle an invoice, after checking cooldown and gas |
209
+ | `seal_and_verify` | Seal an action, read the receipt back, and state what it does and does not prove |
210
+
211
+ ### Resources
212
+
213
+ | URI | Content |
214
+ |---|---|
215
+ | `gblin://contracts` | Every contract in service with its role, and the deprecated deployments not to use |
216
+ | `gblin://payments` | The EIP-712 domain read live from the token, the x402 payload, and the accepts block a seller publishes |
217
+ | `gblin://keys` | The attestor address to pin, and where the log and witness keys are published |
218
+ | `gblin://limits` | Price (free by default), the metering switch, and where the limits come from |
139
219
 
140
220
  ## Usage
141
221
 
@@ -216,7 +296,7 @@ Pay-per-call data lives on HTTP, settled in USDC on Base through the Coinbase CD
216
296
  | `GET gblin.digital/api/x402/invest` | $0.002 | Unsigned calldata: USDC → GBLIN |
217
297
  | `GET gblin.digital/api/x402/jit` | $0.005 | Unsigned calldata: GBLIN → USDC just in time |
218
298
  | `GET gblin.digital/api/x402/attestation` | $0.003 | Signed EIP-712 Risk Attestation, valid ten minutes |
219
- | `POST gblin.digital/api/x402/seal` | $0.01 | A sealed AI Action Receipt |
299
+ | `POST gblin.digital/api/x402/seal` | $0.0045 | A sealed AI Action Receipt |
220
300
 
221
301
  Machine-readable manifest: `https://gblin.digital/.well-known/x402`. Payment recipient: `0x0ebA5d314F4f5Dcb7A094953Fa9311a45172dd1B`.
222
302
 
@@ -237,7 +317,7 @@ receipt = canonical payload
237
317
 
238
318
  Canonicalization is frozen as `gblin-canonical-json/1`: object keys sorted by UTF-16 code unit, no whitespace, `JSON.stringify` semantics for primitives, recursion for objects and arrays. Test vector: payload `{"b":1,"a":null}` → canonical `{"a":null,"b":1}` → leaf = `SHA256(0x00 || canonical_bytes)`. The receipt signature is Ed25519 over `"gblin-receipt/v1\n" + canonical`.
239
319
 
240
- - Seal (paid, unlimited): `POST https://gblin.digital/api/x402/seal`, $0.01 USDC via x402
320
+ - Seal (paid, unlimited): `POST https://gblin.digital/api/x402/seal`, $0.0045 USDC via x402
241
321
  - Seal (demo, 5 per day per IP): `POST <worker>/v1/seal-demo`, or the tool `seal_action_demo`
242
322
  - Read, free: `<worker>/v1/receipt/:index`, `/log`, `/log/checkpoint`, `/log/proof/:index`, `/log/consistency`, `/log/leaves`, and the page `/receipt/:index`
243
323
  - Daily anchor of the tree root on Base as an EAS attestation (schema `0x9f433a96…`)
@@ -271,8 +351,21 @@ git clone https://github.com/gblinproject/gblin-treasury-risk-regime
271
351
  cd gblin-treasury-risk-regime
272
352
  npm install
273
353
  npm run build
274
- npm test # live, read-only smoke test against Base mainnet
275
- npm start # run the compiled server
354
+ npm test # handler smoke test against Base mainnet, read-only
355
+ npm run test:protocol # speaks MCP over stdio: capabilities, instructions, prompts, resources
356
+ npm run test:schemas # every tool through the official MCP client, which validates outputSchema
357
+ npx tsx scripts/test-hosted.ts <url> # the hosted server over Streamable HTTP, with the same validation
358
+ npm start # run the compiled server
359
+ ```
360
+
361
+ Two tests run against a local fork of Base and send transactions there, never on mainnet:
362
+
363
+ ```bash
364
+ anvil --fork-url <base rpc> --port 8555 &
365
+ export GBLIN_RPC_URL=http://127.0.0.1:8555
366
+ npm run test:payments # gasless payment: signed, verified, carried by a third party; replay and front-run refused
367
+ npm run test:calldata # sends the exit and investment steps exactly as the tools return them
368
+ npm run test:actions # every prepare_action, simulated then sent; preview agrees with the chain; gas limits found by bisection
276
369
  ```
277
370
 
278
371
  ```
@@ -282,12 +375,19 @@ src/
282
375
  client.ts # viem public client and on-chain timestamp
283
376
  helpers.ts # NAV, basket state, slippage, cooldown, reverse quote
284
377
  auction.ts # auction state and bid sizing
285
- tools.ts # the ten treasury tools and their schemas
378
+ tools.ts # the treasury, auction and risk tools, and the tool list
379
+ payments.ts # gasless payments (EIP-3009): prepare, verify, relay
380
+ actions.ts # prepare_action, preview_steps, get_transaction_status, get_nav_history
381
+ shared.ts # result envelopes, builder code, Zap routing data and gas limit
382
+ version.ts # generated from package.json by scripts/write-version.mjs
286
383
  receipts.ts # the three receipt tools
287
- index.ts # MCP stdio server entry
384
+ output-schemas.ts # the outputSchema of every tool
385
+ prompts.ts # the four prompts
386
+ resources.ts # the four resources
387
+ index.ts # MCP stdio server entry and initialize instructions
288
388
  init.ts # the gblin-init command
289
389
  worker/ # the hosted Streamable HTTP server (Cloudflare Workers)
290
- scripts/test.ts
390
+ scripts/ # test.ts, test-protocol.ts, test-output-schemas.ts, test-payments-fork.ts, test-calldata-fork.ts
291
391
  ```
292
392
 
293
393
  ## Links
package/dist/abi.d.ts CHANGED
@@ -131,6 +131,33 @@ export declare const GBLIN_ABI: readonly [{
131
131
  readonly stateMutability: "nonpayable";
132
132
  readonly inputs: readonly [];
133
133
  readonly outputs: readonly [];
134
+ }, {
135
+ readonly name: "eip712Domain";
136
+ readonly type: "function";
137
+ readonly stateMutability: "view";
138
+ readonly inputs: readonly [];
139
+ readonly outputs: readonly [{
140
+ readonly type: "bytes1";
141
+ readonly name: "fields";
142
+ }, {
143
+ readonly type: "string";
144
+ readonly name: "name";
145
+ }, {
146
+ readonly type: "string";
147
+ readonly name: "version";
148
+ }, {
149
+ readonly type: "uint256";
150
+ readonly name: "chainId";
151
+ }, {
152
+ readonly type: "address";
153
+ readonly name: "verifyingContract";
154
+ }, {
155
+ readonly type: "bytes32";
156
+ readonly name: "salt";
157
+ }, {
158
+ readonly type: "uint256[]";
159
+ readonly name: "extensions";
160
+ }];
134
161
  }, {
135
162
  readonly name: "authorizationState";
136
163
  readonly type: "function";
package/dist/abi.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"abi.d.ts","sourceRoot":"","sources":["../src/abi.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH;;;GAGG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiCpB,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAkBnB,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAGlB,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiBvB,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAGnC,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAMpB,CAAC"}
1
+ {"version":3,"file":"abi.d.ts","sourceRoot":"","sources":["../src/abi.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH;;;GAGG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAkCpB,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAkBnB,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAGlB,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiBvB,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAGnC,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAMpB,CAAC"}
package/dist/abi.js CHANGED
@@ -26,6 +26,7 @@ export const GBLIN_ABI = parseAbi([
26
26
  "function pendingOwner() view returns (address)",
27
27
  "function acceptOwnership()",
28
28
  // Payments by signature (EIP-3009)
29
+ "function eip712Domain() view returns (bytes1 fields, string name, string version, uint256 chainId, address verifyingContract, bytes32 salt, uint256[] extensions)",
29
30
  "function authorizationState(address authorizer, bytes32 nonce) view returns (bool)",
30
31
  "function transferWithAuthorization(address from, address to, uint256 value, uint256 validAfter, uint256 validBefore, bytes32 nonce, uint8 v, bytes32 r, bytes32 s)",
31
32
  "function receiveWithAuthorization(address from, address to, uint256 value, uint256 validAfter, uint256 validBefore, bytes32 nonce, uint8 v, bytes32 r, bytes32 s)",
package/dist/abi.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"abi.js","sourceRoot":"","sources":["../src/abi.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,MAAM,CAAC;AAEhC;;;GAGG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,QAAQ,CAAC;IAChC,iBAAiB;IACjB,4DAA4D;IAC5D,+CAA+C;IAC/C,0CAA0C;IAC1C,2EAA2E;IAC3E,kEAAkE;IAElE,sBAAsB;IACtB,0EAA0E;IAC1E,kEAAkE;IAClE,8CAA8C;IAC9C,oDAAoD;IACpD,mDAAmD;IAEnD,YAAY;IACZ,yCAAyC;IACzC,gDAAgD;IAChD,4BAA4B;IAE5B,mCAAmC;IACnC,oFAAoF;IACpF,oKAAoK;IACpK,mKAAmK;IACnK,gGAAgG;IAEhG,yEAAyE;IACzE,2CAA2C;IAC3C,6EAA6E;IAC7E,0EAA0E;IAC1E,yCAAyC;IACzC,sCAAsC;IACtC,kJAAkJ;CACnJ,CAAC,CAAC;AAEH;;GAEG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,QAAQ,CAAC;IAC/B,6DAA6D;IAC7D,+LAA+L;IAC/L,6HAA6H;IAC7H,gEAAgE;IAChE,0HAA0H;IAC1H,+EAA+E;IAC/E,qMAAqM;IACrM,kPAAkP;IAClP,iEAAiE;IACjE,yEAAyE;IACzE,gFAAgF;IAChF,iGAAiG;IACjG,6DAA6D;IAC7D,6DAA6D;IAC7D,2DAA2D;IAC3D,8DAA8D;IAC9D,sEAAsE;CACvE,CAAC,CAAC;AAEH;;GAEG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,QAAQ,CAAC;IAC9B,4JAA4J;IAC5J,2HAA2H;CAC5H,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,QAAQ,CAAC;IACnC,+CAA+C;IAC/C,gDAAgD;IAChD,iDAAiD;IACjD,kDAAkD;IAClD,iDAAiD;IACjD,sDAAsD;IACtD,qEAAqE;IACrE,kEAAkE;IAClE,sDAAsD;IACtD,6DAA6D;IAC7D,2DAA2D;IAC3D,0DAA0D;IAC1D,0DAA0D;IAC1D,+IAA+I;IAC/I,qCAAqC;IACrC,0GAA0G;CAC3G,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,QAAQ,CAAC;IAC/C,uIAAuI;IACvI,0CAA0C;CAC3C,CAAC,CAAC;AAEH;;GAEG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,QAAQ,CAAC;IAChC,4DAA4D;IAC5D,0CAA0C;IAC1C,yCAAyC;IACzC,kEAAkE;IAClE,2EAA2E;CAC5E,CAAC,CAAC"}
1
+ {"version":3,"file":"abi.js","sourceRoot":"","sources":["../src/abi.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,MAAM,CAAC;AAEhC;;;GAGG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,QAAQ,CAAC;IAChC,iBAAiB;IACjB,4DAA4D;IAC5D,+CAA+C;IAC/C,0CAA0C;IAC1C,2EAA2E;IAC3E,kEAAkE;IAElE,sBAAsB;IACtB,0EAA0E;IAC1E,kEAAkE;IAClE,8CAA8C;IAC9C,oDAAoD;IACpD,mDAAmD;IAEnD,YAAY;IACZ,yCAAyC;IACzC,gDAAgD;IAChD,4BAA4B;IAE5B,mCAAmC;IACnC,mKAAmK;IACnK,oFAAoF;IACpF,oKAAoK;IACpK,mKAAmK;IACnK,gGAAgG;IAEhG,yEAAyE;IACzE,2CAA2C;IAC3C,6EAA6E;IAC7E,0EAA0E;IAC1E,yCAAyC;IACzC,sCAAsC;IACtC,kJAAkJ;CACnJ,CAAC,CAAC;AAEH;;GAEG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,QAAQ,CAAC;IAC/B,6DAA6D;IAC7D,+LAA+L;IAC/L,6HAA6H;IAC7H,gEAAgE;IAChE,0HAA0H;IAC1H,+EAA+E;IAC/E,qMAAqM;IACrM,kPAAkP;IAClP,iEAAiE;IACjE,yEAAyE;IACzE,gFAAgF;IAChF,iGAAiG;IACjG,6DAA6D;IAC7D,6DAA6D;IAC7D,2DAA2D;IAC3D,8DAA8D;IAC9D,sEAAsE;CACvE,CAAC,CAAC;AAEH;;GAEG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,QAAQ,CAAC;IAC9B,4JAA4J;IAC5J,2HAA2H;CAC5H,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,QAAQ,CAAC;IACnC,+CAA+C;IAC/C,gDAAgD;IAChD,iDAAiD;IACjD,kDAAkD;IAClD,iDAAiD;IACjD,sDAAsD;IACtD,qEAAqE;IACrE,kEAAkE;IAClE,sDAAsD;IACtD,6DAA6D;IAC7D,2DAA2D;IAC3D,0DAA0D;IAC1D,0DAA0D;IAC1D,+IAA+I;IAC/I,qCAAqC;IACrC,0GAA0G;CAC3G,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,QAAQ,CAAC;IAC/C,uIAAuI;IACvI,0CAA0C;CAC3C,CAAC,CAAC;AAEH;;GAEG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,QAAQ,CAAC;IAChC,4DAA4D;IAC5D,0CAA0C;IAC1C,yCAAyC;IACzC,kEAAkE;IAClE,2EAA2E;CAC5E,CAAC,CAAC"}