@crewhaus/tool-evm-tx 0.1.3 → 0.1.5
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/dist/index.d.ts +19 -0
- package/dist/index.js +152 -0
- package/package.json +13 -10
- package/src/index.test.ts +0 -265
- package/src/index.ts +0 -192
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
import type { RegisteredTool } from "@crewhaus/tool-catalog";
|
|
2
|
+
import type { TransactionPolicy, WalletConfig, WalletEngine } from "@crewhaus/wallet-engine";
|
|
3
|
+
/**
|
|
4
|
+
* Resolver pattern matching `tool-evm`. The runtime binds these
|
|
5
|
+
* resolvers at boot from the IR's `wallets[]`, `transaction_policy`,
|
|
6
|
+
* and the engine factory. Tests inline.
|
|
7
|
+
*/
|
|
8
|
+
export type WalletResolver = (walletId: string) => WalletConfig | undefined;
|
|
9
|
+
export type TransactionPolicyResolver = () => TransactionPolicy | undefined;
|
|
10
|
+
export type WalletEngineResolver = () => WalletEngine | undefined;
|
|
11
|
+
export declare function setWalletResolver(fn: WalletResolver): void;
|
|
12
|
+
export declare function setTransactionPolicyResolver(fn: TransactionPolicyResolver): void;
|
|
13
|
+
export declare function setWalletEngineResolver(fn: WalletEngineResolver): void;
|
|
14
|
+
export declare const evmSendTransaction: RegisteredTool;
|
|
15
|
+
export declare const evmSimulate: RegisteredTool;
|
|
16
|
+
export declare const EVM_TX_TOOL_MAP: {
|
|
17
|
+
readonly evmSendTransaction: RegisteredTool;
|
|
18
|
+
readonly evmSimulate: RegisteredTool;
|
|
19
|
+
};
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,152 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Section 47 — `tool-evm-tx`.
|
|
3
|
+
*
|
|
4
|
+
* Destructive EVM transaction tools. Each tool is `destructive: true`
|
|
5
|
+
* so the §7 permission engine auto-gates the call behind an approval
|
|
6
|
+
* prompt; the tool's `execute` then runs the unsigned tx through the
|
|
7
|
+
* §47 `wallet-engine` flow (simulate → static-policy check → approval
|
|
8
|
+
* → custody sign → broadcast → receipt).
|
|
9
|
+
*
|
|
10
|
+
* Catalog layer: R4 (built-in tool implementations). Slice 1.
|
|
11
|
+
*
|
|
12
|
+
* Why the wallet-engine indirection is mandatory: the permission engine
|
|
13
|
+
* gates *whether* the tool may run; the wallet engine enforces *what
|
|
14
|
+
* the tx may do* (allowed contracts, max value, simulation required).
|
|
15
|
+
* Both layers run; the wallet-engine refuses even if a permission rule
|
|
16
|
+
* blanket-allows the tool, and the permission engine refuses even if
|
|
17
|
+
* the transaction-policy is permissive. Two-of-two gates by design.
|
|
18
|
+
*/
|
|
19
|
+
import { buildTool } from "@crewhaus/tool-builder";
|
|
20
|
+
import { z } from "zod";
|
|
21
|
+
let walletResolver;
|
|
22
|
+
let policyResolver;
|
|
23
|
+
let engineResolver;
|
|
24
|
+
export function setWalletResolver(fn) {
|
|
25
|
+
walletResolver = fn;
|
|
26
|
+
}
|
|
27
|
+
export function setTransactionPolicyResolver(fn) {
|
|
28
|
+
policyResolver = fn;
|
|
29
|
+
}
|
|
30
|
+
export function setWalletEngineResolver(fn) {
|
|
31
|
+
engineResolver = fn;
|
|
32
|
+
}
|
|
33
|
+
function requireWallet(walletId, toolName) {
|
|
34
|
+
if (walletResolver === undefined) {
|
|
35
|
+
throw new Error(`${toolName}: no WalletResolver bound. The runtime must call setWalletResolver() at boot.`);
|
|
36
|
+
}
|
|
37
|
+
const w = walletResolver(walletId);
|
|
38
|
+
if (w === undefined) {
|
|
39
|
+
throw new Error(`${toolName}: no wallet registered for walletId "${walletId}". Declare it in spec.wallets[].`);
|
|
40
|
+
}
|
|
41
|
+
return w;
|
|
42
|
+
}
|
|
43
|
+
function requirePolicy(toolName) {
|
|
44
|
+
if (policyResolver === undefined) {
|
|
45
|
+
throw new Error(`${toolName}: no TransactionPolicyResolver bound. The runtime must call setTransactionPolicyResolver() at boot.`);
|
|
46
|
+
}
|
|
47
|
+
const p = policyResolver();
|
|
48
|
+
if (p === undefined) {
|
|
49
|
+
throw new Error(`${toolName}: no transaction_policy declared. Add a transaction_policy block to the spec.`);
|
|
50
|
+
}
|
|
51
|
+
return p;
|
|
52
|
+
}
|
|
53
|
+
function requireEngine(toolName) {
|
|
54
|
+
if (engineResolver === undefined) {
|
|
55
|
+
throw new Error(`${toolName}: no WalletEngine bound. The runtime must call setWalletEngineResolver() at boot.`);
|
|
56
|
+
}
|
|
57
|
+
const e = engineResolver();
|
|
58
|
+
if (e === undefined) {
|
|
59
|
+
throw new Error(`${toolName}: WalletEngine resolver returned undefined.`);
|
|
60
|
+
}
|
|
61
|
+
return e;
|
|
62
|
+
}
|
|
63
|
+
const sendTxSchema = z.object({
|
|
64
|
+
walletId: z.string().min(1).describe("Id of the wallet from spec.wallets[]"),
|
|
65
|
+
contractId: z
|
|
66
|
+
.string()
|
|
67
|
+
.min(1)
|
|
68
|
+
.optional()
|
|
69
|
+
.describe("Id of the target contract from spec.contracts[]. Required when transaction_policy.allowedContracts is non-empty."),
|
|
70
|
+
to: z.string().min(1).describe("Target contract address (0x-prefixed)"),
|
|
71
|
+
data: z.string().min(1).describe("ABI-encoded calldata (0x-prefixed)"),
|
|
72
|
+
value: z
|
|
73
|
+
.string()
|
|
74
|
+
.min(1)
|
|
75
|
+
.optional()
|
|
76
|
+
.describe("Native-token value to send, hex-encoded wei (0x-prefixed). Defaults to 0."),
|
|
77
|
+
gasLimit: z
|
|
78
|
+
.string()
|
|
79
|
+
.min(1)
|
|
80
|
+
.optional()
|
|
81
|
+
.describe("Hex-encoded gas limit. Adapter estimates if omitted."),
|
|
82
|
+
});
|
|
83
|
+
export const evmSendTransaction = buildTool({
|
|
84
|
+
name: "EvmSendTransaction",
|
|
85
|
+
description: "Sign and broadcast an EVM transaction. Goes through the wallet-engine flow: simulate, enforce transaction_policy, prompt approval, sign via custody adapter, broadcast, fetch receipt. Returns the tx hash plus block + status when the receipt is available.",
|
|
86
|
+
inputSchema: sendTxSchema,
|
|
87
|
+
destructive: true,
|
|
88
|
+
classifyOutput: true,
|
|
89
|
+
// Pillar 3 sink-side: broadcasting a tx writes data permanently to a
|
|
90
|
+
// public ledger — the most-external sink we have.
|
|
91
|
+
scope: "external",
|
|
92
|
+
// FR-002 — declare the io-capability fact (RPC broadcast over the network).
|
|
93
|
+
ioCapability: "network",
|
|
94
|
+
// Pillar 3 intent gate: tx broadcast is destructive AND irreversible AND
|
|
95
|
+
// costs money. Mandatory justification gate.
|
|
96
|
+
requireJustification: true,
|
|
97
|
+
execute: async (input) => {
|
|
98
|
+
const wallet = requireWallet(input.walletId, "EvmSendTransaction");
|
|
99
|
+
const policy = requirePolicy("EvmSendTransaction");
|
|
100
|
+
const engine = requireEngine("EvmSendTransaction");
|
|
101
|
+
const tx = {
|
|
102
|
+
chainId: wallet.chainId,
|
|
103
|
+
walletId: wallet.id,
|
|
104
|
+
to: input.to,
|
|
105
|
+
data: input.data,
|
|
106
|
+
...(input.contractId !== undefined ? { contractId: input.contractId } : {}),
|
|
107
|
+
...(input.value !== undefined ? { value: input.value } : {}),
|
|
108
|
+
...(input.gasLimit !== undefined ? { gasLimit: input.gasLimit } : {}),
|
|
109
|
+
};
|
|
110
|
+
const receipt = await engine.requestSignAndBroadcast({ tx, policy, wallet });
|
|
111
|
+
return JSON.stringify({
|
|
112
|
+
txHash: receipt.txHash,
|
|
113
|
+
blockNumber: receipt.blockNumber,
|
|
114
|
+
status: receipt.status,
|
|
115
|
+
});
|
|
116
|
+
},
|
|
117
|
+
});
|
|
118
|
+
const simulateSchema = z.object({
|
|
119
|
+
walletId: z.string().min(1),
|
|
120
|
+
to: z.string().min(1),
|
|
121
|
+
data: z.string().min(1),
|
|
122
|
+
value: z.string().min(1).optional(),
|
|
123
|
+
});
|
|
124
|
+
export const evmSimulate = buildTool({
|
|
125
|
+
name: "EvmSimulate",
|
|
126
|
+
description: "Simulate an EVM transaction without broadcasting. Useful as a pre-flight check before requesting approval. Returns success, gasUsed, returnData, and (if failed) revertReason. No state mutation.",
|
|
127
|
+
inputSchema: simulateSchema,
|
|
128
|
+
readOnly: true,
|
|
129
|
+
concurrencySafe: true,
|
|
130
|
+
execute: async (input) => {
|
|
131
|
+
const wallet = requireWallet(input.walletId, "EvmSimulate");
|
|
132
|
+
const engine = requireEngine("EvmSimulate");
|
|
133
|
+
const tx = {
|
|
134
|
+
chainId: wallet.chainId,
|
|
135
|
+
walletId: wallet.id,
|
|
136
|
+
to: input.to,
|
|
137
|
+
data: input.data,
|
|
138
|
+
...(input.value !== undefined ? { value: input.value } : {}),
|
|
139
|
+
};
|
|
140
|
+
const sim = await engine.simulate({ tx });
|
|
141
|
+
return JSON.stringify({
|
|
142
|
+
success: sim.success,
|
|
143
|
+
gasUsed: sim.gasUsed,
|
|
144
|
+
returnData: sim.returnData,
|
|
145
|
+
revertReason: sim.revertReason,
|
|
146
|
+
});
|
|
147
|
+
},
|
|
148
|
+
});
|
|
149
|
+
export const EVM_TX_TOOL_MAP = {
|
|
150
|
+
evmSendTransaction,
|
|
151
|
+
evmSimulate,
|
|
152
|
+
};
|
package/package.json
CHANGED
|
@@ -1,22 +1,25 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@crewhaus/tool-evm-tx",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.5",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "Built-in destructive EVM transaction tools (EvmSendTransaction, EvmSimulate). All destructive: true — gated by permission-engine approval + wallet-engine policy. §47 slice 1.",
|
|
6
|
-
"main": "
|
|
7
|
-
"types": "
|
|
6
|
+
"main": "dist/index.js",
|
|
7
|
+
"types": "dist/index.d.ts",
|
|
8
8
|
"exports": {
|
|
9
|
-
".":
|
|
9
|
+
".": {
|
|
10
|
+
"types": "./dist/index.d.ts",
|
|
11
|
+
"import": "./dist/index.js"
|
|
12
|
+
}
|
|
10
13
|
},
|
|
11
14
|
"scripts": {
|
|
12
15
|
"test": "bun test src"
|
|
13
16
|
},
|
|
14
17
|
"dependencies": {
|
|
15
|
-
"@crewhaus/chain-adapter-base": "0.1.
|
|
16
|
-
"@crewhaus/errors": "0.1.
|
|
17
|
-
"@crewhaus/tool-builder": "0.1.
|
|
18
|
-
"@crewhaus/tool-catalog": "0.1.
|
|
19
|
-
"@crewhaus/wallet-engine": "0.1.
|
|
18
|
+
"@crewhaus/chain-adapter-base": "0.1.5",
|
|
19
|
+
"@crewhaus/errors": "0.1.5",
|
|
20
|
+
"@crewhaus/tool-builder": "0.1.5",
|
|
21
|
+
"@crewhaus/tool-catalog": "0.1.5",
|
|
22
|
+
"@crewhaus/wallet-engine": "0.1.5",
|
|
20
23
|
"zod": "^3.23.8"
|
|
21
24
|
},
|
|
22
25
|
"license": "Apache-2.0",
|
|
@@ -37,5 +40,5 @@
|
|
|
37
40
|
"publishConfig": {
|
|
38
41
|
"access": "public"
|
|
39
42
|
},
|
|
40
|
-
"files": ["
|
|
43
|
+
"files": ["dist", "README.md", "LICENSE", "NOTICE"]
|
|
41
44
|
}
|
package/src/index.test.ts
DELETED
|
@@ -1,265 +0,0 @@
|
|
|
1
|
-
import { beforeEach, describe, expect, test } from "bun:test";
|
|
2
|
-
import type { ChainAdapter } from "@crewhaus/chain-adapter-base";
|
|
3
|
-
import {
|
|
4
|
-
type TransactionPolicy,
|
|
5
|
-
type WalletConfig,
|
|
6
|
-
createLocalSignerStub,
|
|
7
|
-
createWalletEngine,
|
|
8
|
-
} from "@crewhaus/wallet-engine";
|
|
9
|
-
import {
|
|
10
|
-
EVM_TX_TOOL_MAP,
|
|
11
|
-
setTransactionPolicyResolver,
|
|
12
|
-
setWalletEngineResolver,
|
|
13
|
-
setWalletResolver,
|
|
14
|
-
} from "./index";
|
|
15
|
-
|
|
16
|
-
function fakeAdapter(handler: (method: string) => unknown): ChainAdapter {
|
|
17
|
-
return {
|
|
18
|
-
chainId: "test-chain",
|
|
19
|
-
config: {
|
|
20
|
-
chainId: "test-chain",
|
|
21
|
-
rpcUrls: ["https://stub.test"],
|
|
22
|
-
rpcPolicy: "single",
|
|
23
|
-
finality: { kind: "finalized" },
|
|
24
|
-
reorgTolerant: true,
|
|
25
|
-
},
|
|
26
|
-
async rpcRead(method) {
|
|
27
|
-
return handler(method);
|
|
28
|
-
},
|
|
29
|
-
};
|
|
30
|
-
}
|
|
31
|
-
|
|
32
|
-
const WALLET: WalletConfig = {
|
|
33
|
-
id: "treasury",
|
|
34
|
-
chainId: "test-chain",
|
|
35
|
-
custody: "local",
|
|
36
|
-
signingPolicy: "explicit-user-approval",
|
|
37
|
-
};
|
|
38
|
-
|
|
39
|
-
const POLICY: TransactionPolicy = {
|
|
40
|
-
defaultWriteApproval: "required",
|
|
41
|
-
allowedContracts: ["usdc"],
|
|
42
|
-
simulationRequired: true,
|
|
43
|
-
};
|
|
44
|
-
|
|
45
|
-
beforeEach(() => {
|
|
46
|
-
setWalletResolver(() => undefined);
|
|
47
|
-
setTransactionPolicyResolver(() => undefined);
|
|
48
|
-
setWalletEngineResolver(() => undefined);
|
|
49
|
-
});
|
|
50
|
-
|
|
51
|
-
describe("EvmSendTransaction & EvmSimulate — tool flags", () => {
|
|
52
|
-
test("EvmSendTransaction is destructive and classifies output", () => {
|
|
53
|
-
expect(EVM_TX_TOOL_MAP.evmSendTransaction.destructive).toBe(true);
|
|
54
|
-
expect(EVM_TX_TOOL_MAP.evmSendTransaction.readOnly).toBe(false);
|
|
55
|
-
expect(EVM_TX_TOOL_MAP.evmSendTransaction.classifyOutput).toBe(true);
|
|
56
|
-
});
|
|
57
|
-
test("EvmSimulate is readOnly", () => {
|
|
58
|
-
expect(EVM_TX_TOOL_MAP.evmSimulate.readOnly).toBe(true);
|
|
59
|
-
expect(EVM_TX_TOOL_MAP.evmSimulate.destructive).toBe(false);
|
|
60
|
-
});
|
|
61
|
-
});
|
|
62
|
-
|
|
63
|
-
describe("EvmSendTransaction — happy path through wallet-engine", () => {
|
|
64
|
-
test("broadcasts and returns the receipt", async () => {
|
|
65
|
-
const engine = createWalletEngine({
|
|
66
|
-
resolveAdapter: () =>
|
|
67
|
-
fakeAdapter((method) => {
|
|
68
|
-
if (method === "eth_call") return "0x";
|
|
69
|
-
if (method === "eth_estimateGas") return "0x5208";
|
|
70
|
-
if (method === "eth_getTransactionReceipt") {
|
|
71
|
-
return { blockNumber: "0x100", status: "0x1" };
|
|
72
|
-
}
|
|
73
|
-
return null;
|
|
74
|
-
}),
|
|
75
|
-
approve: async () => "allow",
|
|
76
|
-
});
|
|
77
|
-
engine.registerCustody(createLocalSignerStub());
|
|
78
|
-
setWalletResolver((id) => (id === "treasury" ? WALLET : undefined));
|
|
79
|
-
setTransactionPolicyResolver(() => POLICY);
|
|
80
|
-
setWalletEngineResolver(() => engine);
|
|
81
|
-
|
|
82
|
-
const result = await EVM_TX_TOOL_MAP.evmSendTransaction.execute({
|
|
83
|
-
walletId: "treasury",
|
|
84
|
-
contractId: "usdc",
|
|
85
|
-
to: "0xusdc",
|
|
86
|
-
data: "0xa9059cbb000000",
|
|
87
|
-
});
|
|
88
|
-
const parsed = JSON.parse(result as string);
|
|
89
|
-
expect(parsed.status).toBe("0x1");
|
|
90
|
-
expect(parsed.blockNumber).toBe("0x100");
|
|
91
|
-
expect(typeof parsed.txHash).toBe("string");
|
|
92
|
-
});
|
|
93
|
-
|
|
94
|
-
test("rejects when contractId is not in allowedContracts", async () => {
|
|
95
|
-
const engine = createWalletEngine({
|
|
96
|
-
resolveAdapter: () => fakeAdapter(() => "0x"),
|
|
97
|
-
approve: async () => "allow",
|
|
98
|
-
});
|
|
99
|
-
engine.registerCustody(createLocalSignerStub());
|
|
100
|
-
setWalletResolver(() => WALLET);
|
|
101
|
-
setTransactionPolicyResolver(() => POLICY);
|
|
102
|
-
setWalletEngineResolver(() => engine);
|
|
103
|
-
|
|
104
|
-
await expect(
|
|
105
|
-
EVM_TX_TOOL_MAP.evmSendTransaction.execute({
|
|
106
|
-
walletId: "treasury",
|
|
107
|
-
contractId: "wrong-id",
|
|
108
|
-
to: "0xother",
|
|
109
|
-
data: "0xabcd",
|
|
110
|
-
}),
|
|
111
|
-
).rejects.toThrow(/not in transaction_policy.allowedContracts/);
|
|
112
|
-
});
|
|
113
|
-
|
|
114
|
-
test("denied approval prevents broadcast", async () => {
|
|
115
|
-
const engine = createWalletEngine({
|
|
116
|
-
resolveAdapter: () => fakeAdapter(() => "0x"),
|
|
117
|
-
approve: async () => "deny",
|
|
118
|
-
});
|
|
119
|
-
engine.registerCustody(createLocalSignerStub());
|
|
120
|
-
setWalletResolver(() => WALLET);
|
|
121
|
-
setTransactionPolicyResolver(() => ({ ...POLICY, simulationRequired: false }));
|
|
122
|
-
setWalletEngineResolver(() => engine);
|
|
123
|
-
|
|
124
|
-
await expect(
|
|
125
|
-
EVM_TX_TOOL_MAP.evmSendTransaction.execute({
|
|
126
|
-
walletId: "treasury",
|
|
127
|
-
contractId: "usdc",
|
|
128
|
-
to: "0xusdc",
|
|
129
|
-
data: "0xabcd",
|
|
130
|
-
}),
|
|
131
|
-
).rejects.toThrow(/approval denied/);
|
|
132
|
-
});
|
|
133
|
-
|
|
134
|
-
test("throws when wiring is missing", async () => {
|
|
135
|
-
// beforeEach binds resolvers that return undefined — so we hit the
|
|
136
|
-
// wallet-not-registered branch first.
|
|
137
|
-
await expect(
|
|
138
|
-
EVM_TX_TOOL_MAP.evmSendTransaction.execute({
|
|
139
|
-
walletId: "treasury",
|
|
140
|
-
to: "0xusdc",
|
|
141
|
-
data: "0xabcd",
|
|
142
|
-
}),
|
|
143
|
-
).rejects.toThrow(/no wallet registered for walletId/);
|
|
144
|
-
});
|
|
145
|
-
});
|
|
146
|
-
|
|
147
|
-
describe("resolver-binding guards", () => {
|
|
148
|
-
// These exercise the boot-time "resolver was never bound" branches, which
|
|
149
|
-
// are distinct from a bound resolver returning undefined. The setters assign
|
|
150
|
-
// the module-level resolver directly, so passing undefined clears them.
|
|
151
|
-
test("throws when no WalletResolver is bound", async () => {
|
|
152
|
-
setWalletResolver(undefined as unknown as (id: string) => undefined);
|
|
153
|
-
await expect(
|
|
154
|
-
EVM_TX_TOOL_MAP.evmSendTransaction.execute({
|
|
155
|
-
walletId: "treasury",
|
|
156
|
-
to: "0xusdc",
|
|
157
|
-
data: "0xabcd",
|
|
158
|
-
}),
|
|
159
|
-
).rejects.toThrow(/no WalletResolver bound/);
|
|
160
|
-
});
|
|
161
|
-
|
|
162
|
-
test("throws when no TransactionPolicyResolver is bound", async () => {
|
|
163
|
-
// Wallet resolves OK so we get past requireWallet into requirePolicy.
|
|
164
|
-
setWalletResolver(() => WALLET);
|
|
165
|
-
setTransactionPolicyResolver(undefined as unknown as () => undefined);
|
|
166
|
-
await expect(
|
|
167
|
-
EVM_TX_TOOL_MAP.evmSendTransaction.execute({
|
|
168
|
-
walletId: "treasury",
|
|
169
|
-
to: "0xusdc",
|
|
170
|
-
data: "0xabcd",
|
|
171
|
-
}),
|
|
172
|
-
).rejects.toThrow(/no TransactionPolicyResolver bound/);
|
|
173
|
-
});
|
|
174
|
-
|
|
175
|
-
test("throws when the policy resolver returns undefined", async () => {
|
|
176
|
-
setWalletResolver(() => WALLET);
|
|
177
|
-
setTransactionPolicyResolver(() => undefined);
|
|
178
|
-
await expect(
|
|
179
|
-
EVM_TX_TOOL_MAP.evmSendTransaction.execute({
|
|
180
|
-
walletId: "treasury",
|
|
181
|
-
to: "0xusdc",
|
|
182
|
-
data: "0xabcd",
|
|
183
|
-
}),
|
|
184
|
-
).rejects.toThrow(/no transaction_policy declared/);
|
|
185
|
-
});
|
|
186
|
-
|
|
187
|
-
test("throws when no WalletEngineResolver is bound", async () => {
|
|
188
|
-
// Wallet + policy resolve OK so we reach requireEngine's unbound branch.
|
|
189
|
-
setWalletResolver(() => WALLET);
|
|
190
|
-
setTransactionPolicyResolver(() => POLICY);
|
|
191
|
-
setWalletEngineResolver(undefined as unknown as () => undefined);
|
|
192
|
-
await expect(
|
|
193
|
-
EVM_TX_TOOL_MAP.evmSendTransaction.execute({
|
|
194
|
-
walletId: "treasury",
|
|
195
|
-
contractId: "usdc",
|
|
196
|
-
to: "0xusdc",
|
|
197
|
-
data: "0xabcd",
|
|
198
|
-
}),
|
|
199
|
-
).rejects.toThrow(/no WalletEngine bound/);
|
|
200
|
-
});
|
|
201
|
-
|
|
202
|
-
test("throws when the engine resolver returns undefined (EvmSimulate path)", async () => {
|
|
203
|
-
// EvmSimulate calls requireWallet then requireEngine; a bound resolver
|
|
204
|
-
// returning undefined exercises the `e === undefined` branch.
|
|
205
|
-
setWalletResolver(() => WALLET);
|
|
206
|
-
setWalletEngineResolver(() => undefined);
|
|
207
|
-
await expect(
|
|
208
|
-
EVM_TX_TOOL_MAP.evmSimulate.execute({
|
|
209
|
-
walletId: "treasury",
|
|
210
|
-
to: "0xusdc",
|
|
211
|
-
data: "0xabcd",
|
|
212
|
-
}),
|
|
213
|
-
).rejects.toThrow(/WalletEngine resolver returned undefined/);
|
|
214
|
-
});
|
|
215
|
-
});
|
|
216
|
-
|
|
217
|
-
describe("EvmSimulate", () => {
|
|
218
|
-
test("returns success+gasUsed without broadcasting", async () => {
|
|
219
|
-
const engine = createWalletEngine({
|
|
220
|
-
resolveAdapter: () =>
|
|
221
|
-
fakeAdapter((method) => {
|
|
222
|
-
if (method === "eth_call") return "0x42";
|
|
223
|
-
if (method === "eth_estimateGas") return "0x5208";
|
|
224
|
-
throw new Error(`unexpected method: ${method}`);
|
|
225
|
-
}),
|
|
226
|
-
approve: async () => {
|
|
227
|
-
throw new Error("simulate must not request approval");
|
|
228
|
-
},
|
|
229
|
-
});
|
|
230
|
-
setWalletResolver(() => WALLET);
|
|
231
|
-
setWalletEngineResolver(() => engine);
|
|
232
|
-
|
|
233
|
-
const out = await EVM_TX_TOOL_MAP.evmSimulate.execute({
|
|
234
|
-
walletId: "treasury",
|
|
235
|
-
to: "0xusdc",
|
|
236
|
-
data: "0xabcd",
|
|
237
|
-
});
|
|
238
|
-
const parsed = JSON.parse(out as string);
|
|
239
|
-
expect(parsed.success).toBe(true);
|
|
240
|
-
expect(parsed.gasUsed).toBe("0x5208");
|
|
241
|
-
expect(parsed.returnData).toBe("0x42");
|
|
242
|
-
});
|
|
243
|
-
|
|
244
|
-
test("returns success=false with revertReason on revert", async () => {
|
|
245
|
-
const engine = createWalletEngine({
|
|
246
|
-
resolveAdapter: () =>
|
|
247
|
-
fakeAdapter((method) => {
|
|
248
|
-
if (method === "eth_call") throw new Error("execution reverted: insufficient balance");
|
|
249
|
-
return "0x";
|
|
250
|
-
}),
|
|
251
|
-
approve: async () => "allow",
|
|
252
|
-
});
|
|
253
|
-
setWalletResolver(() => WALLET);
|
|
254
|
-
setWalletEngineResolver(() => engine);
|
|
255
|
-
|
|
256
|
-
const out = await EVM_TX_TOOL_MAP.evmSimulate.execute({
|
|
257
|
-
walletId: "treasury",
|
|
258
|
-
to: "0xusdc",
|
|
259
|
-
data: "0xabcd",
|
|
260
|
-
});
|
|
261
|
-
const parsed = JSON.parse(out as string);
|
|
262
|
-
expect(parsed.success).toBe(false);
|
|
263
|
-
expect(parsed.revertReason).toContain("insufficient balance");
|
|
264
|
-
});
|
|
265
|
-
});
|
package/src/index.ts
DELETED
|
@@ -1,192 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Section 47 — `tool-evm-tx`.
|
|
3
|
-
*
|
|
4
|
-
* Destructive EVM transaction tools. Each tool is `destructive: true`
|
|
5
|
-
* so the §7 permission engine auto-gates the call behind an approval
|
|
6
|
-
* prompt; the tool's `execute` then runs the unsigned tx through the
|
|
7
|
-
* §47 `wallet-engine` flow (simulate → static-policy check → approval
|
|
8
|
-
* → custody sign → broadcast → receipt).
|
|
9
|
-
*
|
|
10
|
-
* Catalog layer: R4 (built-in tool implementations). Slice 1.
|
|
11
|
-
*
|
|
12
|
-
* Why the wallet-engine indirection is mandatory: the permission engine
|
|
13
|
-
* gates *whether* the tool may run; the wallet engine enforces *what
|
|
14
|
-
* the tx may do* (allowed contracts, max value, simulation required).
|
|
15
|
-
* Both layers run; the wallet-engine refuses even if a permission rule
|
|
16
|
-
* blanket-allows the tool, and the permission engine refuses even if
|
|
17
|
-
* the transaction-policy is permissive. Two-of-two gates by design.
|
|
18
|
-
*/
|
|
19
|
-
import { buildTool } from "@crewhaus/tool-builder";
|
|
20
|
-
import type { RegisteredTool } from "@crewhaus/tool-catalog";
|
|
21
|
-
import type {
|
|
22
|
-
TransactionPolicy,
|
|
23
|
-
UnsignedTx,
|
|
24
|
-
WalletConfig,
|
|
25
|
-
WalletEngine,
|
|
26
|
-
} from "@crewhaus/wallet-engine";
|
|
27
|
-
import { z } from "zod";
|
|
28
|
-
|
|
29
|
-
/**
|
|
30
|
-
* Resolver pattern matching `tool-evm`. The runtime binds these
|
|
31
|
-
* resolvers at boot from the IR's `wallets[]`, `transaction_policy`,
|
|
32
|
-
* and the engine factory. Tests inline.
|
|
33
|
-
*/
|
|
34
|
-
export type WalletResolver = (walletId: string) => WalletConfig | undefined;
|
|
35
|
-
export type TransactionPolicyResolver = () => TransactionPolicy | undefined;
|
|
36
|
-
export type WalletEngineResolver = () => WalletEngine | undefined;
|
|
37
|
-
|
|
38
|
-
let walletResolver: WalletResolver | undefined;
|
|
39
|
-
let policyResolver: TransactionPolicyResolver | undefined;
|
|
40
|
-
let engineResolver: WalletEngineResolver | undefined;
|
|
41
|
-
|
|
42
|
-
export function setWalletResolver(fn: WalletResolver): void {
|
|
43
|
-
walletResolver = fn;
|
|
44
|
-
}
|
|
45
|
-
export function setTransactionPolicyResolver(fn: TransactionPolicyResolver): void {
|
|
46
|
-
policyResolver = fn;
|
|
47
|
-
}
|
|
48
|
-
export function setWalletEngineResolver(fn: WalletEngineResolver): void {
|
|
49
|
-
engineResolver = fn;
|
|
50
|
-
}
|
|
51
|
-
|
|
52
|
-
function requireWallet(walletId: string, toolName: string): WalletConfig {
|
|
53
|
-
if (walletResolver === undefined) {
|
|
54
|
-
throw new Error(
|
|
55
|
-
`${toolName}: no WalletResolver bound. The runtime must call setWalletResolver() at boot.`,
|
|
56
|
-
);
|
|
57
|
-
}
|
|
58
|
-
const w = walletResolver(walletId);
|
|
59
|
-
if (w === undefined) {
|
|
60
|
-
throw new Error(
|
|
61
|
-
`${toolName}: no wallet registered for walletId "${walletId}". Declare it in spec.wallets[].`,
|
|
62
|
-
);
|
|
63
|
-
}
|
|
64
|
-
return w;
|
|
65
|
-
}
|
|
66
|
-
|
|
67
|
-
function requirePolicy(toolName: string): TransactionPolicy {
|
|
68
|
-
if (policyResolver === undefined) {
|
|
69
|
-
throw new Error(
|
|
70
|
-
`${toolName}: no TransactionPolicyResolver bound. The runtime must call setTransactionPolicyResolver() at boot.`,
|
|
71
|
-
);
|
|
72
|
-
}
|
|
73
|
-
const p = policyResolver();
|
|
74
|
-
if (p === undefined) {
|
|
75
|
-
throw new Error(
|
|
76
|
-
`${toolName}: no transaction_policy declared. Add a transaction_policy block to the spec.`,
|
|
77
|
-
);
|
|
78
|
-
}
|
|
79
|
-
return p;
|
|
80
|
-
}
|
|
81
|
-
|
|
82
|
-
function requireEngine(toolName: string): WalletEngine {
|
|
83
|
-
if (engineResolver === undefined) {
|
|
84
|
-
throw new Error(
|
|
85
|
-
`${toolName}: no WalletEngine bound. The runtime must call setWalletEngineResolver() at boot.`,
|
|
86
|
-
);
|
|
87
|
-
}
|
|
88
|
-
const e = engineResolver();
|
|
89
|
-
if (e === undefined) {
|
|
90
|
-
throw new Error(`${toolName}: WalletEngine resolver returned undefined.`);
|
|
91
|
-
}
|
|
92
|
-
return e;
|
|
93
|
-
}
|
|
94
|
-
|
|
95
|
-
const sendTxSchema = z.object({
|
|
96
|
-
walletId: z.string().min(1).describe("Id of the wallet from spec.wallets[]"),
|
|
97
|
-
contractId: z
|
|
98
|
-
.string()
|
|
99
|
-
.min(1)
|
|
100
|
-
.optional()
|
|
101
|
-
.describe(
|
|
102
|
-
"Id of the target contract from spec.contracts[]. Required when transaction_policy.allowedContracts is non-empty.",
|
|
103
|
-
),
|
|
104
|
-
to: z.string().min(1).describe("Target contract address (0x-prefixed)"),
|
|
105
|
-
data: z.string().min(1).describe("ABI-encoded calldata (0x-prefixed)"),
|
|
106
|
-
value: z
|
|
107
|
-
.string()
|
|
108
|
-
.min(1)
|
|
109
|
-
.optional()
|
|
110
|
-
.describe("Native-token value to send, hex-encoded wei (0x-prefixed). Defaults to 0."),
|
|
111
|
-
gasLimit: z
|
|
112
|
-
.string()
|
|
113
|
-
.min(1)
|
|
114
|
-
.optional()
|
|
115
|
-
.describe("Hex-encoded gas limit. Adapter estimates if omitted."),
|
|
116
|
-
});
|
|
117
|
-
|
|
118
|
-
export const evmSendTransaction: RegisteredTool = buildTool({
|
|
119
|
-
name: "EvmSendTransaction",
|
|
120
|
-
description:
|
|
121
|
-
"Sign and broadcast an EVM transaction. Goes through the wallet-engine flow: simulate, enforce transaction_policy, prompt approval, sign via custody adapter, broadcast, fetch receipt. Returns the tx hash plus block + status when the receipt is available.",
|
|
122
|
-
inputSchema: sendTxSchema,
|
|
123
|
-
destructive: true,
|
|
124
|
-
classifyOutput: true,
|
|
125
|
-
// Pillar 3 sink-side: broadcasting a tx writes data permanently to a
|
|
126
|
-
// public ledger — the most-external sink we have.
|
|
127
|
-
scope: "external",
|
|
128
|
-
// FR-002 — declare the io-capability fact (RPC broadcast over the network).
|
|
129
|
-
ioCapability: "network",
|
|
130
|
-
// Pillar 3 intent gate: tx broadcast is destructive AND irreversible AND
|
|
131
|
-
// costs money. Mandatory justification gate.
|
|
132
|
-
requireJustification: true,
|
|
133
|
-
execute: async (input) => {
|
|
134
|
-
const wallet = requireWallet(input.walletId, "EvmSendTransaction");
|
|
135
|
-
const policy = requirePolicy("EvmSendTransaction");
|
|
136
|
-
const engine = requireEngine("EvmSendTransaction");
|
|
137
|
-
const tx: UnsignedTx = {
|
|
138
|
-
chainId: wallet.chainId,
|
|
139
|
-
walletId: wallet.id,
|
|
140
|
-
to: input.to,
|
|
141
|
-
data: input.data,
|
|
142
|
-
...(input.contractId !== undefined ? { contractId: input.contractId } : {}),
|
|
143
|
-
...(input.value !== undefined ? { value: input.value } : {}),
|
|
144
|
-
...(input.gasLimit !== undefined ? { gasLimit: input.gasLimit } : {}),
|
|
145
|
-
};
|
|
146
|
-
const receipt = await engine.requestSignAndBroadcast({ tx, policy, wallet });
|
|
147
|
-
return JSON.stringify({
|
|
148
|
-
txHash: receipt.txHash,
|
|
149
|
-
blockNumber: receipt.blockNumber,
|
|
150
|
-
status: receipt.status,
|
|
151
|
-
});
|
|
152
|
-
},
|
|
153
|
-
});
|
|
154
|
-
|
|
155
|
-
const simulateSchema = z.object({
|
|
156
|
-
walletId: z.string().min(1),
|
|
157
|
-
to: z.string().min(1),
|
|
158
|
-
data: z.string().min(1),
|
|
159
|
-
value: z.string().min(1).optional(),
|
|
160
|
-
});
|
|
161
|
-
|
|
162
|
-
export const evmSimulate: RegisteredTool = buildTool({
|
|
163
|
-
name: "EvmSimulate",
|
|
164
|
-
description:
|
|
165
|
-
"Simulate an EVM transaction without broadcasting. Useful as a pre-flight check before requesting approval. Returns success, gasUsed, returnData, and (if failed) revertReason. No state mutation.",
|
|
166
|
-
inputSchema: simulateSchema,
|
|
167
|
-
readOnly: true,
|
|
168
|
-
concurrencySafe: true,
|
|
169
|
-
execute: async (input) => {
|
|
170
|
-
const wallet = requireWallet(input.walletId, "EvmSimulate");
|
|
171
|
-
const engine = requireEngine("EvmSimulate");
|
|
172
|
-
const tx: UnsignedTx = {
|
|
173
|
-
chainId: wallet.chainId,
|
|
174
|
-
walletId: wallet.id,
|
|
175
|
-
to: input.to,
|
|
176
|
-
data: input.data,
|
|
177
|
-
...(input.value !== undefined ? { value: input.value } : {}),
|
|
178
|
-
};
|
|
179
|
-
const sim = await engine.simulate({ tx });
|
|
180
|
-
return JSON.stringify({
|
|
181
|
-
success: sim.success,
|
|
182
|
-
gasUsed: sim.gasUsed,
|
|
183
|
-
returnData: sim.returnData,
|
|
184
|
-
revertReason: sim.revertReason,
|
|
185
|
-
});
|
|
186
|
-
},
|
|
187
|
-
});
|
|
188
|
-
|
|
189
|
-
export const EVM_TX_TOOL_MAP = {
|
|
190
|
-
evmSendTransaction,
|
|
191
|
-
evmSimulate,
|
|
192
|
-
} as const;
|