zk-agent-cli 0.1.0-beta.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 (3) hide show
  1. package/README.md +175 -0
  2. package/dist/index.js +18777 -0
  3. package/package.json +69 -0
package/README.md ADDED
@@ -0,0 +1,175 @@
1
+ # zk-agent-cli
2
+
3
+ `zk-agent-cli` is the packaged `zk-agent-cli` command surface for zkSync Era
4
+ and zkSync Sepolia.
5
+
6
+ Current strengths:
7
+
8
+ - local-first wallet/session storage
9
+ - `next`-first operator guidance
10
+ - relay-backed approval and reapproval
11
+ - workflow orchestration for send, swap, bridge, deposit, and withdraw
12
+ - machine-readable JSON output for agent callers
13
+
14
+ ## Install
15
+
16
+ One-shot execution:
17
+
18
+ ```bash
19
+ npx zk-agent-cli --help
20
+ ```
21
+
22
+ Global install:
23
+
24
+ ```bash
25
+ npm install -g zk-agent-cli
26
+ zk-agent --help
27
+ ```
28
+
29
+ The package also ships the secondary binary name:
30
+
31
+ ```bash
32
+ zksync-agent --help
33
+ ```
34
+
35
+ ## Prerequisites
36
+
37
+ - Node.js `>=24` if you install globally.
38
+ - The default local approval path expects the connector UI to be reachable at
39
+ `http://localhost:4444`. Override it with
40
+ `zk-agent setup --connector-url <url>` when needed.
41
+ - The CLI auto-loads `.env` from the current working directory.
42
+
43
+ You do not need a custom `.env` just to run `setup`, `next`, or create a local
44
+ wallet request. You usually do need one for live chain reads or broadcasts.
45
+
46
+ Most relevant environment variables:
47
+
48
+ ```bash
49
+ ZKSYNC_SEPOLIA_RPC_URL=
50
+ ETHEREUM_SEPOLIA_RPC_URL=
51
+ ZK_AGENT_TOKEN_DIRECTORY_ROOT=
52
+ ZK_AGENT_STORAGE_DIR=
53
+ ```
54
+
55
+ Use:
56
+
57
+ - `ZKSYNC_SEPOLIA_RPC_URL` for explicit zkSync Sepolia reads/broadcasts
58
+ - `ETHEREUM_SEPOLIA_RPC_URL` for L1 deposit/bridge follow-up flows on Sepolia
59
+ - `ZK_AGENT_TOKEN_DIRECTORY_ROOT` when you want local token-directory symbol
60
+ resolution
61
+ - `ZK_AGENT_STORAGE_DIR` only when you need to override the default local
62
+ storage path
63
+
64
+ ## Shortest Path
65
+
66
+ Fresh setup:
67
+
68
+ ```bash
69
+ zk-agent setup
70
+ zk-agent next
71
+ zk-agent wallet create --await-local
72
+ zk-agent next
73
+ zk-agent workflow auto --wallet main --intent <intent> [goal flags] --create-checkpoint --execute-when-ready
74
+ ```
75
+
76
+ If a wallet already exists and only the writable session is stale, use:
77
+
78
+ ```bash
79
+ zk-agent wallet reapprove --name main --await-local
80
+ zk-agent next
81
+ ```
82
+
83
+ Only fund when the CLI says funding is actually required:
84
+
85
+ ```bash
86
+ zk-agent workflow fund --wallet main --amount <amount> --execute
87
+ ```
88
+
89
+ ## Remote Approval
90
+
91
+ Shortest relay-backed path in one command:
92
+
93
+ ```bash
94
+ zk-agent wallet create --relay-url <relay-url> --wait-relay --prompt-code
95
+ zk-agent wallet reapprove --name main --relay-url <relay-url> --wait-relay --prompt-code
96
+ ```
97
+
98
+ Local relay prototype path:
99
+
100
+ ```bash
101
+ zk-agent relay serve
102
+ zk-agent wallet create --relay-url <relay-url>
103
+ zk-agent wallet request approve --request-id <id> --relay-url <relay-url> --code <code> --wait
104
+ ```
105
+
106
+ The built-in relay is a local file-backed prototype. It is useful for operator
107
+ testing, not a production hosted relay service.
108
+
109
+ ## Local Storage
110
+
111
+ By default the CLI stores config, wallets, requests, and workflow checkpoints
112
+ under:
113
+
114
+ ```text
115
+ ~/.zk-agent/
116
+ ```
117
+
118
+ Common files created by the default path:
119
+
120
+ - `config.json`
121
+ - `wallets/*.json`
122
+ - `requests/*.json`
123
+ - `workflow-checkpoints/*.json`
124
+
125
+ ## Smart-Account Profiles
126
+
127
+ The published package can inspect built-in profiles:
128
+
129
+ ```bash
130
+ zk-agent wallet smart-account profiles --json
131
+ ```
132
+
133
+ Current boundary:
134
+
135
+ - profile inspection works from the packaged CLI
136
+ - built-in profile deploys still require
137
+ `ZK_AGENT_ACCOUNT_PROFILES_ROOT=<checked-out account-profiles package dir>`
138
+ because the npm tarball does not ship the EraVM profile artifacts
139
+
140
+ ## Common Failures
141
+
142
+ Connector callback never arrives:
143
+
144
+ - verify the connector URL saved by `zk-agent setup`
145
+ - if local callback is not possible in your environment, switch to the relay
146
+ path with `zk-agent relay serve` plus `wallet create|reapprove --relay-url`
147
+
148
+ CLI says the wallet is missing a writable session:
149
+
150
+ - run `zk-agent wallet reapprove --name <wallet> --await-local`
151
+ - then rerun `zk-agent next` or the blocked workflow command
152
+
153
+ Workflow stops on funding:
154
+
155
+ - do not guess the route
156
+ - run the exact `workflow fund` command suggested by the CLI
157
+
158
+ Relay / `--await-local` flows fail in a locked-down environment:
159
+
160
+ - those flows need a process that can bind `127.0.0.1`
161
+ - rerun from a normal host shell or use the relay/manual approval path
162
+
163
+ ## Command Help
164
+
165
+ For the canonical command surfaces:
166
+
167
+ ```bash
168
+ zk-agent --help
169
+ zk-agent wallet --help
170
+ zk-agent workflow --help
171
+ ```
172
+
173
+ ## License
174
+
175
+ MIT. See the repository `LICENSE`.