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.
Files changed (49) hide show
  1. xian_tech_wallet_cli-0.2.1/AGENTS.md +14 -0
  2. xian_tech_wallet_cli-0.2.1/LICENSE +21 -0
  3. xian_tech_wallet_cli-0.2.1/MANIFEST.in +4 -0
  4. xian_tech_wallet_cli-0.2.1/PKG-INFO +145 -0
  5. xian_tech_wallet_cli-0.2.1/README.md +120 -0
  6. xian_tech_wallet_cli-0.2.1/docs/ARCHITECTURE.md +45 -0
  7. xian_tech_wallet_cli-0.2.1/docs/BACKLOG.md +10 -0
  8. xian_tech_wallet_cli-0.2.1/docs/WALLET.md +136 -0
  9. xian_tech_wallet_cli-0.2.1/pyproject.toml +56 -0
  10. xian_tech_wallet_cli-0.2.1/setup.cfg +4 -0
  11. xian_tech_wallet_cli-0.2.1/src/xian_tech_wallet_cli.egg-info/PKG-INFO +145 -0
  12. xian_tech_wallet_cli-0.2.1/src/xian_tech_wallet_cli.egg-info/SOURCES.txt +47 -0
  13. xian_tech_wallet_cli-0.2.1/src/xian_tech_wallet_cli.egg-info/dependency_links.txt +1 -0
  14. xian_tech_wallet_cli-0.2.1/src/xian_tech_wallet_cli.egg-info/entry_points.txt +2 -0
  15. xian_tech_wallet_cli-0.2.1/src/xian_tech_wallet_cli.egg-info/requires.txt +13 -0
  16. xian_tech_wallet_cli-0.2.1/src/xian_tech_wallet_cli.egg-info/top_level.txt +1 -0
  17. xian_tech_wallet_cli-0.2.1/src/xian_wallet_cli/__init__.py +0 -0
  18. xian_tech_wallet_cli-0.2.1/src/xian_wallet_cli/accounts_cli.py +148 -0
  19. xian_tech_wallet_cli-0.2.1/src/xian_wallet_cli/activity.py +120 -0
  20. xian_tech_wallet_cli-0.2.1/src/xian_wallet_cli/agent_cli.py +418 -0
  21. xian_tech_wallet_cli-0.2.1/src/xian_wallet_cli/chain.py +306 -0
  22. xian_tech_wallet_cli-0.2.1/src/xian_wallet_cli/chain_apps.py +291 -0
  23. xian_tech_wallet_cli-0.2.1/src/xian_wallet_cli/cli.py +424 -0
  24. xian_tech_wallet_cli-0.2.1/src/xian_wallet_cli/dashboard.py +213 -0
  25. xian_tech_wallet_cli-0.2.1/src/xian_wallet_cli/domain.py +259 -0
  26. xian_tech_wallet_cli-0.2.1/src/xian_wallet_cli/files.py +63 -0
  27. xian_tech_wallet_cli-0.2.1/src/xian_wallet_cli/payments.py +278 -0
  28. xian_tech_wallet_cli-0.2.1/src/xian_wallet_cli/permissions.py +173 -0
  29. xian_tech_wallet_cli-0.2.1/src/xian_wallet_cli/presentation.py +203 -0
  30. xian_tech_wallet_cli-0.2.1/src/xian_wallet_cli/profiles.py +157 -0
  31. xian_tech_wallet_cli-0.2.1/src/xian_wallet_cli/shielded.py +329 -0
  32. xian_tech_wallet_cli-0.2.1/src/xian_wallet_cli/state.py +84 -0
  33. xian_tech_wallet_cli-0.2.1/src/xian_wallet_cli/telegram.py +121 -0
  34. xian_tech_wallet_cli-0.2.1/src/xian_wallet_cli/vault.py +115 -0
  35. xian_tech_wallet_cli-0.2.1/src/xian_wallet_cli/walletconnect/bridge.mjs +199 -0
  36. xian_tech_wallet_cli-0.2.1/src/xian_wallet_cli/walletconnect/package-lock.json +1044 -0
  37. xian_tech_wallet_cli-0.2.1/src/xian_wallet_cli/walletconnect/package.json +10 -0
  38. xian_tech_wallet_cli-0.2.1/src/xian_wallet_cli/walletconnect/policy.mjs +37 -0
  39. xian_tech_wallet_cli-0.2.1/src/xian_wallet_cli/walletconnect_cli.py +106 -0
  40. xian_tech_wallet_cli-0.2.1/tests/conftest.py +6 -0
  41. xian_tech_wallet_cli-0.2.1/tests/test_accounts.py +48 -0
  42. xian_tech_wallet_cli-0.2.1/tests/test_advanced.py +99 -0
  43. xian_tech_wallet_cli-0.2.1/tests/test_boundaries.py +125 -0
  44. xian_tech_wallet_cli-0.2.1/tests/test_calls.py +27 -0
  45. xian_tech_wallet_cli-0.2.1/tests/test_dashboard.py +76 -0
  46. xian_tech_wallet_cli-0.2.1/tests/test_permissions.py +143 -0
  47. xian_tech_wallet_cli-0.2.1/tests/test_telegram.py +18 -0
  48. xian_tech_wallet_cli-0.2.1/tests/test_wallet.py +226 -0
  49. 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,4 @@
1
+ include AGENTS.md
2
+ include tests/conftest.py
3
+ include tests/walletconnect.test.mjs
4
+ recursive-include docs *.md
@@ -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
+ ![The Accounts tab shows a demo balance, public address, and receive QR code](https://raw.githubusercontent.com/xian-technology/xian-wallet-cli/main/docs/screenshots/account-overview.png)
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
+ ![Transfer review showing a demo amount, sender, recipient, network, chi limit, and signing controls](https://raw.githubusercontent.com/xian-technology/xian-wallet-cli/main/docs/screenshots/transaction-review.png)
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
+ ![The Accounts tab shows a demo balance, public address, and receive QR code](https://raw.githubusercontent.com/xian-technology/xian-wallet-cli/main/docs/screenshots/account-overview.png)
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
+ ![Transfer review showing a demo amount, sender, recipient, network, chi limit, and signing controls](https://raw.githubusercontent.com/xian-technology/xian-wallet-cli/main/docs/screenshots/transaction-review.png)
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"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+