xian-tech-wallet-cli 0.2.1__tar.gz
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.
- xian_tech_wallet_cli-0.2.1/AGENTS.md +14 -0
- xian_tech_wallet_cli-0.2.1/LICENSE +21 -0
- xian_tech_wallet_cli-0.2.1/MANIFEST.in +4 -0
- xian_tech_wallet_cli-0.2.1/PKG-INFO +145 -0
- xian_tech_wallet_cli-0.2.1/README.md +120 -0
- xian_tech_wallet_cli-0.2.1/docs/ARCHITECTURE.md +45 -0
- xian_tech_wallet_cli-0.2.1/docs/BACKLOG.md +10 -0
- xian_tech_wallet_cli-0.2.1/docs/WALLET.md +136 -0
- xian_tech_wallet_cli-0.2.1/pyproject.toml +56 -0
- xian_tech_wallet_cli-0.2.1/setup.cfg +4 -0
- xian_tech_wallet_cli-0.2.1/src/xian_tech_wallet_cli.egg-info/PKG-INFO +145 -0
- xian_tech_wallet_cli-0.2.1/src/xian_tech_wallet_cli.egg-info/SOURCES.txt +47 -0
- xian_tech_wallet_cli-0.2.1/src/xian_tech_wallet_cli.egg-info/dependency_links.txt +1 -0
- xian_tech_wallet_cli-0.2.1/src/xian_tech_wallet_cli.egg-info/entry_points.txt +2 -0
- xian_tech_wallet_cli-0.2.1/src/xian_tech_wallet_cli.egg-info/requires.txt +13 -0
- xian_tech_wallet_cli-0.2.1/src/xian_tech_wallet_cli.egg-info/top_level.txt +1 -0
- xian_tech_wallet_cli-0.2.1/src/xian_wallet_cli/__init__.py +0 -0
- xian_tech_wallet_cli-0.2.1/src/xian_wallet_cli/accounts_cli.py +148 -0
- xian_tech_wallet_cli-0.2.1/src/xian_wallet_cli/activity.py +120 -0
- xian_tech_wallet_cli-0.2.1/src/xian_wallet_cli/agent_cli.py +418 -0
- xian_tech_wallet_cli-0.2.1/src/xian_wallet_cli/chain.py +306 -0
- xian_tech_wallet_cli-0.2.1/src/xian_wallet_cli/chain_apps.py +291 -0
- xian_tech_wallet_cli-0.2.1/src/xian_wallet_cli/cli.py +424 -0
- xian_tech_wallet_cli-0.2.1/src/xian_wallet_cli/dashboard.py +213 -0
- xian_tech_wallet_cli-0.2.1/src/xian_wallet_cli/domain.py +259 -0
- xian_tech_wallet_cli-0.2.1/src/xian_wallet_cli/files.py +63 -0
- xian_tech_wallet_cli-0.2.1/src/xian_wallet_cli/payments.py +278 -0
- xian_tech_wallet_cli-0.2.1/src/xian_wallet_cli/permissions.py +173 -0
- xian_tech_wallet_cli-0.2.1/src/xian_wallet_cli/presentation.py +203 -0
- xian_tech_wallet_cli-0.2.1/src/xian_wallet_cli/profiles.py +157 -0
- xian_tech_wallet_cli-0.2.1/src/xian_wallet_cli/shielded.py +329 -0
- xian_tech_wallet_cli-0.2.1/src/xian_wallet_cli/state.py +84 -0
- xian_tech_wallet_cli-0.2.1/src/xian_wallet_cli/telegram.py +121 -0
- xian_tech_wallet_cli-0.2.1/src/xian_wallet_cli/vault.py +115 -0
- xian_tech_wallet_cli-0.2.1/src/xian_wallet_cli/walletconnect/bridge.mjs +199 -0
- xian_tech_wallet_cli-0.2.1/src/xian_wallet_cli/walletconnect/package-lock.json +1044 -0
- xian_tech_wallet_cli-0.2.1/src/xian_wallet_cli/walletconnect/package.json +10 -0
- xian_tech_wallet_cli-0.2.1/src/xian_wallet_cli/walletconnect/policy.mjs +37 -0
- xian_tech_wallet_cli-0.2.1/src/xian_wallet_cli/walletconnect_cli.py +106 -0
- xian_tech_wallet_cli-0.2.1/tests/conftest.py +6 -0
- xian_tech_wallet_cli-0.2.1/tests/test_accounts.py +48 -0
- xian_tech_wallet_cli-0.2.1/tests/test_advanced.py +99 -0
- xian_tech_wallet_cli-0.2.1/tests/test_boundaries.py +125 -0
- xian_tech_wallet_cli-0.2.1/tests/test_calls.py +27 -0
- xian_tech_wallet_cli-0.2.1/tests/test_dashboard.py +76 -0
- xian_tech_wallet_cli-0.2.1/tests/test_permissions.py +143 -0
- xian_tech_wallet_cli-0.2.1/tests/test_telegram.py +18 -0
- xian_tech_wallet_cli-0.2.1/tests/test_wallet.py +226 -0
- xian_tech_wallet_cli-0.2.1/tests/walletconnect.test.mjs +20 -0
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
# Repository Guidelines
|
|
2
|
+
|
|
3
|
+
- Start with [README.md](README.md) for commands and
|
|
4
|
+
[architecture](docs/ARCHITECTURE.md) for signing, submission, and rendering.
|
|
5
|
+
- Follow the [workspace conventions](../xian-meta/docs/REPO_CONVENTIONS.md)
|
|
6
|
+
and [change workflow](../xian-meta/docs/CHANGE_WORKFLOW.md).
|
|
7
|
+
- Reuse the published `xian-tech-py` transaction and wallet primitives. Keep
|
|
8
|
+
approval files bound to exact proposal contents and transaction bytes.
|
|
9
|
+
- Keep secret keys out of command-line arguments, JSON, logs, and agent-facing
|
|
10
|
+
commands. Validate changes against a disposable localnet.
|
|
11
|
+
- Run `uv run ruff check`, `uv run ruff format --check`, and `uv run pytest`.
|
|
12
|
+
Update the wallet CLI skill and public docs when user workflows change.
|
|
13
|
+
- For codebase questions and graph updates, follow the shared
|
|
14
|
+
[code graph workflow](../xian-meta/docs/CODE_GRAPH_WORKFLOW.md).
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Xian Technology
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,145 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: xian-tech-wallet-cli
|
|
3
|
+
Version: 0.2.1
|
|
4
|
+
Summary: Xian wallet for terminals and agents
|
|
5
|
+
License-Expression: MIT
|
|
6
|
+
Project-URL: Homepage, https://github.com/xian-technology/xian-wallet-cli
|
|
7
|
+
Project-URL: Documentation, https://docs.xian.technology/tools/xian-wallet-cli
|
|
8
|
+
Project-URL: Issues, https://github.com/xian-technology/xian-wallet-cli/issues
|
|
9
|
+
Requires-Python: <3.15,>=3.14
|
|
10
|
+
Description-Content-Type: text/markdown
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
Requires-Dist: aiohttp<4,>=3.13.5
|
|
13
|
+
Requires-Dist: pydantic<3,>=2.12
|
|
14
|
+
Requires-Dist: pynacl<2,>=1.6
|
|
15
|
+
Requires-Dist: qrcode<9,>=8
|
|
16
|
+
Requires-Dist: rich<16,>=14
|
|
17
|
+
Requires-Dist: textual<9,>=6
|
|
18
|
+
Requires-Dist: typer<1,>=0.26
|
|
19
|
+
Requires-Dist: xian-tech-py[hd]<0.6,>=0.5.3
|
|
20
|
+
Requires-Dist: xian-tech-runtime-types<0.2,>=0.1.6
|
|
21
|
+
Requires-Dist: yarl<2,>=1.20
|
|
22
|
+
Provides-Extra: shielded
|
|
23
|
+
Requires-Dist: xian-tech-zk<0.3,>=0.2.1; extra == "shielded"
|
|
24
|
+
Dynamic: license-file
|
|
25
|
+
|
|
26
|
+
# Xian Wallet CLI
|
|
27
|
+
|
|
28
|
+
`xian-wallet` is a terminal wallet for Xian. It combines named accounts,
|
|
29
|
+
encrypted recovery backups, portfolio and activity views, and transaction
|
|
30
|
+
approval for people and agents. The CLI, Textual interface, and signer service
|
|
31
|
+
use the same Xian SDK transaction format.
|
|
32
|
+
|
|
33
|
+
## Install
|
|
34
|
+
|
|
35
|
+
Use Python 3.14 and uv on macOS or Linux.
|
|
36
|
+
|
|
37
|
+
```sh
|
|
38
|
+
uv tool install xian-tech-wallet-cli
|
|
39
|
+
xian-wallet --help
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
For shielded notes, install with `uv tool install 'xian-tech-wallet-cli[shielded]'`.
|
|
43
|
+
If uv reports that its executable directory is outside `PATH`, run
|
|
44
|
+
`uv tool update-shell` and open a fresh terminal.
|
|
45
|
+
|
|
46
|
+
Control the state directory with `--home` or `XIAN_WALLET_HOME`. It defaults
|
|
47
|
+
to `$XDG_STATE_HOME/xian-wallet` or `~/.local/state/xian-wallet`.
|
|
48
|
+
|
|
49
|
+
## Accounts and networks
|
|
50
|
+
|
|
51
|
+
```sh
|
|
52
|
+
xian-wallet account create primary
|
|
53
|
+
xian-wallet account backup primary --out primary.backup.json
|
|
54
|
+
xian-wallet receive primary --qr
|
|
55
|
+
xian-wallet ui
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+

|
|
59
|
+
|
|
60
|
+
Use `account restore NAME --mnemonic-file FILE --index INDEX` for the same
|
|
61
|
+
mnemonic-derived address as the browser and mobile wallets. Use
|
|
62
|
+
`account import-key NAME --key-file FILE` for a previously generated raw
|
|
63
|
+
Ed25519 key, `account derive SOURCE NAME --index INDEX` for another account
|
|
64
|
+
from the same recovery phrase, and `account watch NAME ADDRESS` for a public
|
|
65
|
+
address. `account restore-backup FILE` verifies an encrypted CLI backup before
|
|
66
|
+
restoring it. `account export-recovery NAME --out FILE` writes the mnemonic
|
|
67
|
+
to an owner-only file for offline storage.
|
|
68
|
+
|
|
69
|
+
The vault unlocks only for each sensitive operation and prompts for its
|
|
70
|
+
password locally. Trusted signer processes can use `--password-file` for
|
|
71
|
+
an explicitly provisioned owner-only file. Use a separate OS identity or
|
|
72
|
+
host for a signer that serves agents.
|
|
73
|
+
|
|
74
|
+
The default RPC is `http://127.0.0.1:26657`. For a saved network, obtain the
|
|
75
|
+
chain ID and first-block hash from a trusted source. Add it with
|
|
76
|
+
`network add NAME URL --chain-id ID --first-block-hash HASH`, then select it
|
|
77
|
+
with `network use NAME` or the global `--network NAME` option. Named profiles
|
|
78
|
+
allow explicit HTTPS RPCs. The node must be synced and serve block 1.
|
|
79
|
+
|
|
80
|
+
## Review and send
|
|
81
|
+
|
|
82
|
+
```sh
|
|
83
|
+
xian-wallet contact add recipient "$RECIPIENT_ADDRESS"
|
|
84
|
+
xian-wallet prepare --from primary --to recipient --amount 1.25 --out proposal.json
|
|
85
|
+
xian-wallet approve proposal.json --account primary --out approval.json --textual
|
|
86
|
+
xian-wallet submit proposal.json --approval approval.json
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+

|
|
90
|
+
|
|
91
|
+
Use `--token CONTRACT` for a fungible token. `token watch NAME CONTRACT`
|
|
92
|
+
adds a token to `portfolio ACCOUNT`. `activity` reads the local approval and
|
|
93
|
+
receipt journal. `incoming ACCOUNT --token CONTRACT` scans a page of
|
|
94
|
+
BDS-indexed transfers. Use the returned `next_offset` to keep scanning if a
|
|
95
|
+
page lacks matches.
|
|
96
|
+
|
|
97
|
+
Use `call CONTRACT FUNCTION --args ARGS.json` for read-only simulation.
|
|
98
|
+
Use `prepare-call` to prepare a typed write. Generic fractional values use
|
|
99
|
+
`{"__fixed__":"1.25"}`. The simulator and signing flow share the exact
|
|
100
|
+
payload. `dex`, `nft`, `message`, `x402`, `shielded`, and `walletconnect`
|
|
101
|
+
provide the product-specific workflows in the [wallet guide](https://github.com/xian-technology/xian-wallet-cli/blob/main/docs/WALLET.md).
|
|
102
|
+
|
|
103
|
+
## Agent approvals
|
|
104
|
+
|
|
105
|
+
The agent prepares a proposal and submits it to the trusted signer with
|
|
106
|
+
`agent request`. The owner reviews it using the Textual inbox or a configured
|
|
107
|
+
Telegram bot. The agent then uses `agent fetch` to obtain the signed approval
|
|
108
|
+
and submits it with `submit`. Use `grant` to opt into autonomous, revocable
|
|
109
|
+
transfers within an account, network, asset, recipient, amount, chi budget,
|
|
110
|
+
and expiry. The agent needs the signer socket or an SSH socket forward and
|
|
111
|
+
the relevant bearer credential. [Signer setup and examples](https://github.com/xian-technology/xian-wallet-cli/blob/main/docs/WALLET.md#agent-approvals)
|
|
112
|
+
|
|
113
|
+
Put `--json` before the command for one `xian-wallet-cli/v1` result on stdout.
|
|
114
|
+
Amounts are decimal strings. Normal usage errors go to stderr.
|
|
115
|
+
|
|
116
|
+
| Exit | Meaning |
|
|
117
|
+
| --- | --- |
|
|
118
|
+
| 0 | Command succeeded, or transfer committed successfully |
|
|
119
|
+
| 1 | Admission rejection, failed execution, or failed verification |
|
|
120
|
+
| 2 | Command, input, approval, file, or RPC error |
|
|
121
|
+
| 3 | Final outcome is pending or unknown |
|
|
122
|
+
|
|
123
|
+
After interruption, use `receipt TX_HASH` or retry the same proposal and
|
|
124
|
+
approval. The wallet only signs competing same-nonce proposals through an
|
|
125
|
+
explicit owner replacement. Keep the original hash available until one of
|
|
126
|
+
the competing transactions is finalized.
|
|
127
|
+
|
|
128
|
+
## Validation
|
|
129
|
+
|
|
130
|
+
From a source checkout, use `uv run xian-wallet --help` to run the CLI.
|
|
131
|
+
|
|
132
|
+
```sh
|
|
133
|
+
uv run --extra shielded ruff check
|
|
134
|
+
uv run --extra shielded ruff format --check
|
|
135
|
+
uv run --extra shielded pytest
|
|
136
|
+
node --test tests/walletconnect.test.mjs
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
## Related Docs
|
|
140
|
+
|
|
141
|
+
- [Wallet guide](https://github.com/xian-technology/xian-wallet-cli/blob/main/docs/WALLET.md)
|
|
142
|
+
- [Architecture](https://github.com/xian-technology/xian-wallet-cli/blob/main/docs/ARCHITECTURE.md)
|
|
143
|
+
- [Backlog](https://github.com/xian-technology/xian-wallet-cli/blob/main/docs/BACKLOG.md)
|
|
144
|
+
- [Xian Python SDK](https://github.com/xian-technology/xian-py)
|
|
145
|
+
- [Agent wallet skill](https://github.com/xian-technology/xian-ai-skills/blob/main/xian-wallet-cli-skill/SKILL.md)
|
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
# Xian Wallet CLI
|
|
2
|
+
|
|
3
|
+
`xian-wallet` is a terminal wallet for Xian. It combines named accounts,
|
|
4
|
+
encrypted recovery backups, portfolio and activity views, and transaction
|
|
5
|
+
approval for people and agents. The CLI, Textual interface, and signer service
|
|
6
|
+
use the same Xian SDK transaction format.
|
|
7
|
+
|
|
8
|
+
## Install
|
|
9
|
+
|
|
10
|
+
Use Python 3.14 and uv on macOS or Linux.
|
|
11
|
+
|
|
12
|
+
```sh
|
|
13
|
+
uv tool install xian-tech-wallet-cli
|
|
14
|
+
xian-wallet --help
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
For shielded notes, install with `uv tool install 'xian-tech-wallet-cli[shielded]'`.
|
|
18
|
+
If uv reports that its executable directory is outside `PATH`, run
|
|
19
|
+
`uv tool update-shell` and open a fresh terminal.
|
|
20
|
+
|
|
21
|
+
Control the state directory with `--home` or `XIAN_WALLET_HOME`. It defaults
|
|
22
|
+
to `$XDG_STATE_HOME/xian-wallet` or `~/.local/state/xian-wallet`.
|
|
23
|
+
|
|
24
|
+
## Accounts and networks
|
|
25
|
+
|
|
26
|
+
```sh
|
|
27
|
+
xian-wallet account create primary
|
|
28
|
+
xian-wallet account backup primary --out primary.backup.json
|
|
29
|
+
xian-wallet receive primary --qr
|
|
30
|
+
xian-wallet ui
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+

|
|
34
|
+
|
|
35
|
+
Use `account restore NAME --mnemonic-file FILE --index INDEX` for the same
|
|
36
|
+
mnemonic-derived address as the browser and mobile wallets. Use
|
|
37
|
+
`account import-key NAME --key-file FILE` for a previously generated raw
|
|
38
|
+
Ed25519 key, `account derive SOURCE NAME --index INDEX` for another account
|
|
39
|
+
from the same recovery phrase, and `account watch NAME ADDRESS` for a public
|
|
40
|
+
address. `account restore-backup FILE` verifies an encrypted CLI backup before
|
|
41
|
+
restoring it. `account export-recovery NAME --out FILE` writes the mnemonic
|
|
42
|
+
to an owner-only file for offline storage.
|
|
43
|
+
|
|
44
|
+
The vault unlocks only for each sensitive operation and prompts for its
|
|
45
|
+
password locally. Trusted signer processes can use `--password-file` for
|
|
46
|
+
an explicitly provisioned owner-only file. Use a separate OS identity or
|
|
47
|
+
host for a signer that serves agents.
|
|
48
|
+
|
|
49
|
+
The default RPC is `http://127.0.0.1:26657`. For a saved network, obtain the
|
|
50
|
+
chain ID and first-block hash from a trusted source. Add it with
|
|
51
|
+
`network add NAME URL --chain-id ID --first-block-hash HASH`, then select it
|
|
52
|
+
with `network use NAME` or the global `--network NAME` option. Named profiles
|
|
53
|
+
allow explicit HTTPS RPCs. The node must be synced and serve block 1.
|
|
54
|
+
|
|
55
|
+
## Review and send
|
|
56
|
+
|
|
57
|
+
```sh
|
|
58
|
+
xian-wallet contact add recipient "$RECIPIENT_ADDRESS"
|
|
59
|
+
xian-wallet prepare --from primary --to recipient --amount 1.25 --out proposal.json
|
|
60
|
+
xian-wallet approve proposal.json --account primary --out approval.json --textual
|
|
61
|
+
xian-wallet submit proposal.json --approval approval.json
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+

|
|
65
|
+
|
|
66
|
+
Use `--token CONTRACT` for a fungible token. `token watch NAME CONTRACT`
|
|
67
|
+
adds a token to `portfolio ACCOUNT`. `activity` reads the local approval and
|
|
68
|
+
receipt journal. `incoming ACCOUNT --token CONTRACT` scans a page of
|
|
69
|
+
BDS-indexed transfers. Use the returned `next_offset` to keep scanning if a
|
|
70
|
+
page lacks matches.
|
|
71
|
+
|
|
72
|
+
Use `call CONTRACT FUNCTION --args ARGS.json` for read-only simulation.
|
|
73
|
+
Use `prepare-call` to prepare a typed write. Generic fractional values use
|
|
74
|
+
`{"__fixed__":"1.25"}`. The simulator and signing flow share the exact
|
|
75
|
+
payload. `dex`, `nft`, `message`, `x402`, `shielded`, and `walletconnect`
|
|
76
|
+
provide the product-specific workflows in the [wallet guide](https://github.com/xian-technology/xian-wallet-cli/blob/main/docs/WALLET.md).
|
|
77
|
+
|
|
78
|
+
## Agent approvals
|
|
79
|
+
|
|
80
|
+
The agent prepares a proposal and submits it to the trusted signer with
|
|
81
|
+
`agent request`. The owner reviews it using the Textual inbox or a configured
|
|
82
|
+
Telegram bot. The agent then uses `agent fetch` to obtain the signed approval
|
|
83
|
+
and submits it with `submit`. Use `grant` to opt into autonomous, revocable
|
|
84
|
+
transfers within an account, network, asset, recipient, amount, chi budget,
|
|
85
|
+
and expiry. The agent needs the signer socket or an SSH socket forward and
|
|
86
|
+
the relevant bearer credential. [Signer setup and examples](https://github.com/xian-technology/xian-wallet-cli/blob/main/docs/WALLET.md#agent-approvals)
|
|
87
|
+
|
|
88
|
+
Put `--json` before the command for one `xian-wallet-cli/v1` result on stdout.
|
|
89
|
+
Amounts are decimal strings. Normal usage errors go to stderr.
|
|
90
|
+
|
|
91
|
+
| Exit | Meaning |
|
|
92
|
+
| --- | --- |
|
|
93
|
+
| 0 | Command succeeded, or transfer committed successfully |
|
|
94
|
+
| 1 | Admission rejection, failed execution, or failed verification |
|
|
95
|
+
| 2 | Command, input, approval, file, or RPC error |
|
|
96
|
+
| 3 | Final outcome is pending or unknown |
|
|
97
|
+
|
|
98
|
+
After interruption, use `receipt TX_HASH` or retry the same proposal and
|
|
99
|
+
approval. The wallet only signs competing same-nonce proposals through an
|
|
100
|
+
explicit owner replacement. Keep the original hash available until one of
|
|
101
|
+
the competing transactions is finalized.
|
|
102
|
+
|
|
103
|
+
## Validation
|
|
104
|
+
|
|
105
|
+
From a source checkout, use `uv run xian-wallet --help` to run the CLI.
|
|
106
|
+
|
|
107
|
+
```sh
|
|
108
|
+
uv run --extra shielded ruff check
|
|
109
|
+
uv run --extra shielded ruff format --check
|
|
110
|
+
uv run --extra shielded pytest
|
|
111
|
+
node --test tests/walletconnect.test.mjs
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
## Related Docs
|
|
115
|
+
|
|
116
|
+
- [Wallet guide](https://github.com/xian-technology/xian-wallet-cli/blob/main/docs/WALLET.md)
|
|
117
|
+
- [Architecture](https://github.com/xian-technology/xian-wallet-cli/blob/main/docs/ARCHITECTURE.md)
|
|
118
|
+
- [Backlog](https://github.com/xian-technology/xian-wallet-cli/blob/main/docs/BACKLOG.md)
|
|
119
|
+
- [Xian Python SDK](https://github.com/xian-technology/xian-py)
|
|
120
|
+
- [Agent wallet skill](https://github.com/xian-technology/xian-ai-skills/blob/main/xian-wallet-cli-skill/SKILL.md)
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
# Wallet CLI architecture
|
|
2
|
+
|
|
3
|
+
`domain.py` models the original transfer proposal and the typed contract
|
|
4
|
+
proposal. Both commit to a network identity, nonce, chi limit, exact payload,
|
|
5
|
+
and expiry. The signer produces a domain-bound approval and the exact SDK
|
|
6
|
+
transaction signature. Signing and submission verify that identity and the
|
|
7
|
+
transaction hash. The original v1 native transfer messages retain their
|
|
8
|
+
wire shape.
|
|
9
|
+
|
|
10
|
+
`state.py` owns the local SQLite transaction boundary. Public account
|
|
11
|
+
metadata, contacts, profiles and watched assets are separate from custody.
|
|
12
|
+
`vault.py` encrypts account secrets with Argon2id and XChaCha20-Poly1305.
|
|
13
|
+
Authenticated data binds each secret to its public account, derivation
|
|
14
|
+
index, and backup version. Plaintext recovery stays in owner-only files or
|
|
15
|
+
in memory for the active operation. A watch-only account has no secret.
|
|
16
|
+
|
|
17
|
+
`activity.py` records transaction hashes, receipts and signing reservations.
|
|
18
|
+
The signer serializes signing by network, address and nonce. Revocable
|
|
19
|
+
grant counters and the exact signing reservation commit in one database
|
|
20
|
+
transaction. The journal captures the transaction hash before broadcast so
|
|
21
|
+
it remains available on restart. SDK committed receipts override pending
|
|
22
|
+
attempts. An explicit owner replacement names the previous transaction
|
|
23
|
+
hash and competes for the same nonce.
|
|
24
|
+
|
|
25
|
+
`agent_cli.py` exposes request and approval exchange over a Unix socket.
|
|
26
|
+
The owner configures authentication and authorizes the action through a
|
|
27
|
+
terminal inbox, the Telegram bridge or a preauthorized transfer grant.
|
|
28
|
+
The agent receives the signed artifact and owns submission and recovery.
|
|
29
|
+
The signer database and password live under the signer’s OS authority.
|
|
30
|
+
Revoking a grant prevents future signing and the chain enforces replay
|
|
31
|
+
protection on released signatures.
|
|
32
|
+
|
|
33
|
+
`chain.py` adapts the Xian SDK for simulation, identity, balance, event
|
|
34
|
+
reads and finality. Public HTTPS RPCs use an explicit saved identity.
|
|
35
|
+
`chain_apps.py`, `payments.py`, and `shielded.py` own reviewed product
|
|
36
|
+
operations. x402 keeps its independent permit nonce ledger. Shielded
|
|
37
|
+
operations use the native proof toolkit and encrypted local snapshots.
|
|
38
|
+
The optional WalletConnect sidecar validates session scope and invokes
|
|
39
|
+
the same CLI review and signer for each write.
|
|
40
|
+
|
|
41
|
+
Rich previews, the Textual wallet and the remote review format use
|
|
42
|
+
the same proposal structure. The UI borrows the browser wallet's dark
|
|
43
|
+
surfaces and green accent. Accounts expose receiving addresses and a QR,
|
|
44
|
+
activity preserves status by transaction hash, and each approval presents
|
|
45
|
+
the exact call and limits before signing.
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
# Backlog
|
|
2
|
+
|
|
3
|
+
- Add external custody providers and hardware signing where the provider can
|
|
4
|
+
enforce the Xian transaction and message contracts.
|
|
5
|
+
- Broaden DEX coverage to multi-hop and fee-on-transfer routes with dedicated
|
|
6
|
+
review of effective amounts.
|
|
7
|
+
- Add shielded relay submission and integration coverage with promoted
|
|
8
|
+
proving bundles and a full BDS-backed localnet.
|
|
9
|
+
- Expand messaging and WalletConnect integration coverage with real test
|
|
10
|
+
accounts and relay credentials.
|
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
# Wallet workflows
|
|
2
|
+
|
|
3
|
+
## Automation conventions
|
|
4
|
+
|
|
5
|
+
Use a wallet home for the trusted signer and a separate one for the agent.
|
|
6
|
+
Put global flags such as `--home`, `--network`, and `--json` before the
|
|
7
|
+
command. The sender argument accepts a named account or public address.
|
|
8
|
+
The recipient accepts a contact or a public address. Use the contract name
|
|
9
|
+
as the asset identifier in commands, even when a watchlist entry uses a
|
|
10
|
+
friendly display name.
|
|
11
|
+
|
|
12
|
+
Retain the proposal and approval files until finality. A proposal is a
|
|
13
|
+
snapshot of the current nonce, simulation and fee ceiling. Prepare a fresh
|
|
14
|
+
proposal for changed parameters or a stale nonce. After an ambiguous RPC
|
|
15
|
+
response, resolve the original hash before preparing a replacement.
|
|
16
|
+
|
|
17
|
+
## Agent approvals
|
|
18
|
+
|
|
19
|
+
On the trusted signer host, save a random 32-byte hex request token to an
|
|
20
|
+
owner-only file with `umask 077`. Provide a dedicated copy to the agent.
|
|
21
|
+
Start the signer with a Unix socket in an owner-controlled directory:
|
|
22
|
+
|
|
23
|
+
```sh
|
|
24
|
+
xian-wallet agent serve --socket "$SIGNER_SOCKET" --request-token-file request.token
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
The owner can review new requests from `xian-wallet ui`, or run
|
|
28
|
+
`inbox review PROPOSAL_ID --account OWNER`. With a dedicated Telegram bot,
|
|
29
|
+
let the owner open the bot's private chat before enabling the connection.
|
|
30
|
+
Add `--telegram-token-file BOT_TOKEN`, `--telegram-owner-id USER_ID`,
|
|
31
|
+
`--telegram-account OWNER`, and `--password-file PASSWORD_FILE` to
|
|
32
|
+
`agent serve` for automatic review. Each Telegram decision is bound to the
|
|
33
|
+
authenticated user's private chat and the message for the exact proposal.
|
|
34
|
+
For a one-off review, use `inbox telegram PROPOSAL_ID --account OWNER
|
|
35
|
+
--token-file BOT_TOKEN --owner-id USER_ID`. Large contract calls can use
|
|
36
|
+
the Textual inbox.
|
|
37
|
+
|
|
38
|
+
On the agent side, point `SIGNER_SOCKET` at an SSH-forwarded copy of the
|
|
39
|
+
signer's socket when running under a different identity or on another host:
|
|
40
|
+
|
|
41
|
+
```sh
|
|
42
|
+
xian-wallet --json agent request proposal.json --socket "$SIGNER_SOCKET" --token-file request.token
|
|
43
|
+
xian-wallet --json agent fetch "$PROPOSAL_ID" --socket "$SIGNER_SOCKET" --token-file request.token --out approval.json
|
|
44
|
+
xian-wallet --json submit proposal.json --approval approval.json
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
Poll `fetch` until the status is `approved` or `declined`, or the proposal
|
|
48
|
+
expires. The request token gives access to the inbox for that service,
|
|
49
|
+
including its signed handoffs. Use a dedicated signer instance for an agent
|
|
50
|
+
trust group, and share the grant credential only with the authorized agent.
|
|
51
|
+
|
|
52
|
+
For unattended recurring transfers, the owner runs:
|
|
53
|
+
|
|
54
|
+
```sh
|
|
55
|
+
xian-wallet --network local grant create payroll --account primary \
|
|
56
|
+
--recipient "$RECIPIENT" --contract currency --tx-limit 1.25 --total-limit 10 \
|
|
57
|
+
--max-chi 1000 --total-chi 10000 --seconds 3600 --out payroll.token
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
Run the signer with `--password-file` to enable grant signing. Give the agent
|
|
61
|
+
only the grant token, which works with `agent authorize payroll PROPOSAL
|
|
62
|
+
--socket SOCKET --token-file payroll.token --out approval.json`.
|
|
63
|
+
`grant list` shows used amount and chi. `grant revoke payroll` stops future
|
|
64
|
+
signing. A previously issued approval remains relayable by anyone holding
|
|
65
|
+
it, and the chain consumes its nonce once. Budgets charge at signing time,
|
|
66
|
+
so an unsubmitted or failed transaction still counts against the grant.
|
|
67
|
+
|
|
68
|
+
The owner can sign a competing proposal with `approve --replaces OLD_HASH`
|
|
69
|
+
after resolving the old receipt. Both signed transactions can be relayed,
|
|
70
|
+
and only one can consume the nonce. Keep that operation owner-controlled.
|
|
71
|
+
|
|
72
|
+
## DEX and NFTs
|
|
73
|
+
|
|
74
|
+
`dex quote TOKEN_IN TOKEN_OUT AMOUNT --from ACCOUNT` quotes an exact-input
|
|
75
|
+
single-pair swap. Use `dex allowance TOKEN_IN AMOUNT --from ACCOUNT --out
|
|
76
|
+
allowance.json` to review the amount the router can spend. An amount of zero
|
|
77
|
+
revokes that on-chain allowance. After the allowance finalizes, use
|
|
78
|
+
`dex prepare TOKEN_IN TOKEN_OUT AMOUNT --from ACCOUNT --to RECIPIENT
|
|
79
|
+
--slippage-bps BPS --out swap.json`. Its preview includes the exact amount,
|
|
80
|
+
minimum output, recipient, pair and deadline. The current flow uses
|
|
81
|
+
standard-transfer tokens on the direct router pair.
|
|
82
|
+
|
|
83
|
+
Use `nft inspect COLLECTION TOKEN_ID` to read ownership and metadata.
|
|
84
|
+
`nft transfer COLLECTION TOKEN_ID --from ACCOUNT --to RECIPIENT --out
|
|
85
|
+
nft.json` uses the same approval flow as a fungible transfer.
|
|
86
|
+
|
|
87
|
+
## Message signing and WalletConnect
|
|
88
|
+
|
|
89
|
+
`message sign MESSAGE_FILE --account ACCOUNT --out signature.json` displays
|
|
90
|
+
the UTF-8 message and signs the browser-compatible Xian chain/account
|
|
91
|
+
envelope. `message verify MESSAGE_FILE signature.json` verifies it locally.
|
|
92
|
+
|
|
93
|
+
Install the optional transport with `walletconnect setup` on Node.js 22 or
|
|
94
|
+
later, set `XIAN_WALLETCONNECT_PROJECT_ID` to your Reown project ID, and
|
|
95
|
+
run `walletconnect pair --account ACCOUNT --network PROFILE`. Pairing
|
|
96
|
+
requests identify scope, chain and account. Terminal confirmation is
|
|
97
|
+
required to connect and to sign each write. The app pairs for one selected
|
|
98
|
+
chain and account. The scope includes account reads, message signing, and
|
|
99
|
+
preparing, signing or sending transactions and contract calls. Ctrl+C
|
|
100
|
+
disconnects the active sessions.
|
|
101
|
+
|
|
102
|
+
## x402 payments
|
|
103
|
+
|
|
104
|
+
Use `x402 quote URL --from ACCOUNT --to PAYEE --asset TOKEN
|
|
105
|
+
--max-amount AMOUNT --settlement CONTRACT --out offer.json` to fetch an
|
|
106
|
+
exact HTTP 402 challenge. The command matches the payee, chain, asset,
|
|
107
|
+
amount ceiling, settlement contract and exact HTTPS or loopback resource.
|
|
108
|
+
Approve with `x402 approve offer.json --account ACCOUNT --out payment.json`.
|
|
109
|
+
The agent runs `x402 submit offer.json payment.json --out response.data`.
|
|
110
|
+
The same signed payment ID can be retried if the resource response is lost.
|
|
111
|
+
This flow uses GET resources and the SDK's Xian x402 v2 exact profile.
|
|
112
|
+
|
|
113
|
+
## Shielded notes
|
|
114
|
+
|
|
115
|
+
Install the optional proof SDK with `uv tool install 'xian-tech-wallet-cli[shielded]'`.
|
|
116
|
+
Select the profile for a chain with the zk feature, a deployed shielded-note
|
|
117
|
+
contract, its matching registered proof bundle, and BDS. Keep encrypted
|
|
118
|
+
snapshots and recovery seeds with the owner.
|
|
119
|
+
|
|
120
|
+
- `shielded create CONTRACT --out snapshot.json` creates a shielded account.
|
|
121
|
+
Use `--seed-file` to recover one. `shielded export-recovery` writes an
|
|
122
|
+
owner-only seed file. `shielded receive SNAPSHOT --out recipient.json`
|
|
123
|
+
exports only public shielded receiving keys.
|
|
124
|
+
- `shielded sync SNAPSHOT --out synced.json` scans indexed output records,
|
|
125
|
+
updates spent status and writes an encrypted replacement snapshot.
|
|
126
|
+
- `shielded prepare ACTION SNAPSHOT --from ACCOUNT --amount UNITS
|
|
127
|
+
--bundle TRUSTED_BUNDLE --out proposal.json` reviews the private terms
|
|
128
|
+
and proves locally. Actions are `deposit`, `transfer`, and `withdraw`.
|
|
129
|
+
For `transfer`, `--to` is a public shielded recipient file. For
|
|
130
|
+
`withdraw`, `--to` is a public Xian address or saved contact.
|
|
131
|
+
The resulting proposal carries public proof data. Use the normal
|
|
132
|
+
transaction approval and receipt workflow to submit it.
|
|
133
|
+
|
|
134
|
+
Direct shielded transactions can expose the transaction origin. The input
|
|
135
|
+
notes and shielded recipient are reviewed on the owner machine before
|
|
136
|
+
proving. Resync after commitment or when recovering from an older snapshot.
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=77.0.3", "wheel"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "xian-tech-wallet-cli"
|
|
7
|
+
version = "0.2.1"
|
|
8
|
+
description = "Xian wallet for terminals and agents"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.14,<3.15"
|
|
11
|
+
license = "MIT"
|
|
12
|
+
license-files = ["LICENSE"]
|
|
13
|
+
dependencies = [
|
|
14
|
+
"aiohttp>=3.13.5,<4",
|
|
15
|
+
"pydantic>=2.12,<3",
|
|
16
|
+
"pynacl>=1.6,<2",
|
|
17
|
+
"qrcode>=8,<9",
|
|
18
|
+
"rich>=14,<16",
|
|
19
|
+
"textual>=6,<9",
|
|
20
|
+
"typer>=0.26,<1",
|
|
21
|
+
"xian-tech-py[hd]>=0.5.3,<0.6",
|
|
22
|
+
"xian-tech-runtime-types>=0.1.6,<0.2",
|
|
23
|
+
"yarl>=1.20,<2",
|
|
24
|
+
]
|
|
25
|
+
|
|
26
|
+
[project.urls]
|
|
27
|
+
Homepage = "https://github.com/xian-technology/xian-wallet-cli"
|
|
28
|
+
Documentation = "https://docs.xian.technology/tools/xian-wallet-cli"
|
|
29
|
+
Issues = "https://github.com/xian-technology/xian-wallet-cli/issues"
|
|
30
|
+
|
|
31
|
+
[project.scripts]
|
|
32
|
+
xian-wallet = "xian_wallet_cli.cli:app"
|
|
33
|
+
|
|
34
|
+
[project.optional-dependencies]
|
|
35
|
+
shielded = [
|
|
36
|
+
"xian-tech-zk>=0.2.1,<0.3",
|
|
37
|
+
]
|
|
38
|
+
|
|
39
|
+
[dependency-groups]
|
|
40
|
+
dev = ["pytest>=9,<10", "pytest-cov>=7,<8", "ruff>=0.15,<0.16"]
|
|
41
|
+
|
|
42
|
+
[tool.setuptools.packages.find]
|
|
43
|
+
where = ["src"]
|
|
44
|
+
|
|
45
|
+
[tool.setuptools.package-data]
|
|
46
|
+
xian_wallet_cli = ["walletconnect/*.mjs", "walletconnect/package*.json"]
|
|
47
|
+
|
|
48
|
+
[tool.pytest.ini_options]
|
|
49
|
+
testpaths = ["tests"]
|
|
50
|
+
|
|
51
|
+
[tool.ruff]
|
|
52
|
+
line-length = 100
|
|
53
|
+
target-version = "py314"
|
|
54
|
+
|
|
55
|
+
[tool.ruff.lint]
|
|
56
|
+
select = ["E", "F", "I"]
|