@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.
- package/AGENTS.md +49 -20
- package/README.md +111 -11
- package/dist/abi.d.ts +27 -0
- package/dist/abi.d.ts.map +1 -1
- package/dist/abi.js +1 -0
- package/dist/abi.js.map +1 -1
- package/dist/actions.d.ts +306 -0
- package/dist/actions.d.ts.map +1 -0
- package/dist/actions.js +749 -0
- package/dist/actions.js.map +1 -0
- package/dist/auction.d.ts.map +1 -1
- package/dist/auction.js +5 -4
- package/dist/auction.js.map +1 -1
- package/dist/config.d.ts +20 -3
- package/dist/config.d.ts.map +1 -1
- package/dist/config.js +23 -6
- package/dist/config.js.map +1 -1
- package/dist/helpers.d.ts +6 -0
- package/dist/helpers.d.ts.map +1 -1
- package/dist/helpers.js +37 -13
- package/dist/helpers.js.map +1 -1
- package/dist/index.d.ts +3 -4
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +38 -19
- package/dist/index.js.map +1 -1
- package/dist/output-schemas.d.ts +18 -0
- package/dist/output-schemas.d.ts.map +1 -0
- package/dist/output-schemas.js +243 -0
- package/dist/output-schemas.js.map +1 -0
- package/dist/payments.d.ts +170 -0
- package/dist/payments.d.ts.map +1 -0
- package/dist/payments.js +524 -0
- package/dist/payments.js.map +1 -0
- package/dist/paywall.d.ts +10 -1
- package/dist/paywall.d.ts.map +1 -1
- package/dist/paywall.js +1 -1
- package/dist/paywall.js.map +1 -1
- package/dist/prompts.d.ts +33 -0
- package/dist/prompts.d.ts.map +1 -0
- package/dist/prompts.js +139 -0
- package/dist/prompts.js.map +1 -0
- package/dist/receipts.d.ts +2 -1
- package/dist/receipts.d.ts.map +1 -1
- package/dist/receipts.js +16 -12
- package/dist/receipts.js.map +1 -1
- package/dist/resources.d.ts +17 -0
- package/dist/resources.d.ts.map +1 -0
- package/dist/resources.js +146 -0
- package/dist/resources.js.map +1 -0
- package/dist/shared.d.ts +35 -0
- package/dist/shared.d.ts.map +1 -0
- package/dist/shared.js +68 -0
- package/dist/shared.js.map +1 -0
- package/dist/tools.d.ts +106 -19
- package/dist/tools.d.ts.map +1 -1
- package/dist/tools.js +124 -117
- package/dist/tools.js.map +1 -1
- package/dist/version.d.ts +2 -0
- package/dist/version.d.ts.map +1 -0
- package/dist/version.js +3 -0
- package/dist/version.js.map +1 -0
- package/llms.txt +24 -2
- 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
|
+
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
|
|
39
|
-
|
|
40
|
-
|
|
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
|
|
54
|
-
| `src/tools.ts` |
|
|
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
|
|
64
|
-
npm test
|
|
65
|
-
npm run
|
|
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 (
|
|
113
|
+
call swap_gblin_to_usdc_jit (three transactions, batchable → enough USDC to pay)
|
|
100
114
|
```
|
|
101
115
|
|
|
102
|
-
### The
|
|
116
|
+
### The twenty tools
|
|
103
117
|
|
|
104
118
|
| Tool | Use it when |
|
|
105
119
|
| --- | --- |
|
|
106
|
-
| `get_market_risk_regime` | Before any risk decision
|
|
107
|
-
| `verify_risk_attestation` | Verify a peer's
|
|
108
|
-
| `get_treasury_state` | Read live NAV, basket weights,
|
|
109
|
-
| `quote_safe_swap` | Preview a
|
|
110
|
-
| `swap_gblin_to_usdc_jit` | Pay an
|
|
111
|
-
| `invest_usdc_to_gblin` |
|
|
112
|
-
| `analyze_treasury_health` |
|
|
113
|
-
| `get_governance_state` | Owner,
|
|
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
|
|
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
|
-
-
|
|
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
|
|
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
|
|
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.
|
|
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.
|
|
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
|
|
275
|
-
npm
|
|
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
|
|
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
|
-
|
|
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
|
|
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"}
|