polarka-agent 0.1.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 (31) hide show
  1. polarka_agent-0.1.1/.gitignore +5 -0
  2. polarka_agent-0.1.1/LICENSE +21 -0
  3. polarka_agent-0.1.1/PKG-INFO +180 -0
  4. polarka_agent-0.1.1/README.md +158 -0
  5. polarka_agent-0.1.1/REVIEW.md +28 -0
  6. polarka_agent-0.1.1/polarka_agent/__init__.py +2 -0
  7. polarka_agent-0.1.1/polarka_agent/__main__.py +3 -0
  8. polarka_agent-0.1.1/polarka_agent/cli.py +197 -0
  9. polarka_agent-0.1.1/polarka_agent/english.txt +2048 -0
  10. polarka_agent-0.1.1/polarka_agent/faucet.py +283 -0
  11. polarka_agent-0.1.1/polarka_agent/keys.py +318 -0
  12. polarka_agent-0.1.1/polarka_agent/mcp.py +145 -0
  13. polarka_agent-0.1.1/polarka_agent/postage.py +223 -0
  14. polarka_agent-0.1.1/polarka_agent/server.py +449 -0
  15. polarka_agent-0.1.1/polarka_agent/tx.py +178 -0
  16. polarka_agent-0.1.1/polarka_agent/wallet.py +479 -0
  17. polarka_agent-0.1.1/pyproject.toml +52 -0
  18. polarka_agent-0.1.1/review/report-0.1.0.dev0.md +318 -0
  19. polarka_agent-0.1.1/tests/__init__.py +0 -0
  20. polarka_agent-0.1.1/tests/bench.py +96 -0
  21. polarka_agent-0.1.1/tests/fake.py +84 -0
  22. polarka_agent-0.1.1/tests/faults.py +77 -0
  23. polarka_agent-0.1.1/tests/p2qrh-test-vectors.json +260 -0
  24. polarka_agent-0.1.1/tests/standin/northbound_standin.py +654 -0
  25. polarka_agent-0.1.1/tests/test_cli_mcp.py +217 -0
  26. polarka_agent-0.1.1/tests/test_faucet.py +128 -0
  27. polarka_agent-0.1.1/tests/test_keys_tx.py +211 -0
  28. polarka_agent-0.1.1/tests/test_postage.py +134 -0
  29. polarka_agent-0.1.1/tests/test_server.py +283 -0
  30. polarka_agent-0.1.1/tests/test_wallet.py +337 -0
  31. polarka_agent-0.1.1/tests/test_wallet_rules.py +266 -0
@@ -0,0 +1,5 @@
1
+ __pycache__/
2
+ *.pyc
3
+ .DS_Store
4
+ wallets/
5
+ dist/
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Severka
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,180 @@
1
+ Metadata-Version: 2.4
2
+ Name: polarka-agent
3
+ Version: 0.1.1
4
+ Summary: A wallet for TrueNorth (NORTH) that a program can use: command line, Python library and MCP server.
5
+ Project-URL: Homepage, https://polarka.org
6
+ Project-URL: Source, https://github.com/severka-monitor/polarka-agent
7
+ Project-URL: Issues, https://github.com/severka-monitor/polarka-agent/issues
8
+ Author: Severka
9
+ License-Expression: MIT
10
+ License-File: LICENSE
11
+ Keywords: agent,cryptocurrency,mcp,north,truenorth,wallet
12
+ Classifier: Development Status :: 3 - Alpha
13
+ Classifier: Environment :: Console
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: Operating System :: MacOS
16
+ Classifier: Operating System :: POSIX :: Linux
17
+ Classifier: Programming Language :: Python :: 3
18
+ Classifier: Programming Language :: Python :: 3 :: Only
19
+ Classifier: Topic :: Office/Business :: Financial
20
+ Requires-Python: >=3.9
21
+ Description-Content-Type: text/markdown
22
+
23
+ # Polarka Agent
24
+
25
+ A wallet for TrueNorth (NORTH) that a program can use: a command line, a Python library, and a server for
26
+ agents that speak the Model Context Protocol (MCP). The keys stay on the machine it runs on. What its
27
+ addresses hold it asks a wallet server with the Northbound API (github.com/nova9/northbound).
28
+
29
+ **State: 0.1.1, an early version.** It was written with an AI model under its author's direction. An
30
+ independent AI reviewer read it and found faults, the serious ones of which are mended (`REVIEW.md`); no
31
+ human security expert has read it. On 17 November 2026 it made its first payments on the real network: two
32
+ small payments went into blocks, and its owner's limits refused what they should (`NO_LIMITS`, `OVER_LIMIT`,
33
+ `OVER_DAY`). That is all the real use it has had. Do not put into it what you cannot lose. It is an independent community project, not a product of the TrueNorth developers or of
34
+ the Northbound project.
35
+
36
+ ## What it is for
37
+
38
+ A program that has a processor and no bank account can earn NORTH by mining and can be paid in it. This
39
+ wallet lets such a program hold coins and pay small amounts by itself, within bounds that a person sets and
40
+ that the tools given to the program cannot change.
41
+
42
+ ## How a program is kept within bounds
43
+
44
+ - Without a file `limits.json` in the wallet's folder the wallet pays nothing. Its owner writes that file by
45
+ hand: `{"per_payment_north": "5", "per_day_north": "20"}`, and if wanted `"allow": [addresses]` and
46
+ `"fee_rate"`. No command and no tool of the MCP server writes or changes it.
47
+ - Every transaction is written into `journal.jsonl` before anything leaves the machine. Lines are only added.
48
+ - The MCP server has no tool that shows the recovery words, changes the limits or forgets a payment.
49
+ - These bounds hold against a program that reaches the wallet through the MCP server only. A program that
50
+ can run commands or write files as the same user can change `limits.json`, move the journal away or read
51
+ the words; against that the wallet does nothing. Give an agent the MCP server, not a shell in that account.
52
+ - A payment counts into its day whatever became of it; only the owner's `forget` takes one out. A payment
53
+ that another one replaced therefore counts twice for a day.
54
+ - What a wallet server says in words is not passed on to the program: a refusal comes as one of a few fixed
55
+ words and an error as its HTTP status.
56
+
57
+ The recovery words are in `wallet.json`, readable by its owner only (mode 600; the program refuses to work
58
+ with a file that others can read). Whoever can read that file can spend. This is a wallet for small amounts
59
+ on a machine its owner controls.
60
+
61
+ ## Paying, and a server that says no
62
+
63
+ The rules are those of the Polarka Wallet for Android, which an independent reviewer looked at.
64
+
65
+ Whoever was shown a signed transaction can keep it and pass it on later, whatever they answered. So a
66
+ payment that the server refused (`kept`) or that got lost (`unknown`) is not forgotten. The next payment is
67
+ built on one of its coins, and only one of the two can ever be in a block. The same payment asked for again
68
+ (same coins, same outputs) is the same transaction and is simply shown to the server once more. While the
69
+ server shows none of the coins of such a payment, the wallet pays nothing at all, until its owner has looked
70
+ at the wallet through another server or a node and forgets the payment by hand (`forget`).
71
+
72
+ A wallet server sees the wallet's addresses together and the machine's internet address. It can show a false
73
+ balance or hold a payment back. It can stop the wallet until its owner acts (by refusing a payment and then
74
+ hiding its coins), and it can keep one command waiting for a long time by answering slowly. It cannot take
75
+ coins. A program is not shown the server's own words: why a node refused a payment comes as one of a few
76
+ fixed words (`FEE_TOO_LOW`, `INPUTS_GONE`, `OTHER`, ...), an error as its HTTP status, and a receiver in the
77
+ history only if it has the shape of an address. The words themselves appear at the command line alone,
78
+ under `server_said_untrusted`, for the owner.
79
+
80
+ ## Installing
81
+
82
+ pip install polarka-agent
83
+
84
+ That gives the command `polarka-agent`, which is the same as `python3 -m polarka_agent`. It needs Python 3.9
85
+ or later on Linux or macOS and nothing besides; it does not run on Windows. The package on PyPI is built from
86
+ this repository at the tag of its version.
87
+
88
+ ## Commands
89
+
90
+ python3 -m polarka_agent --dir FOLDER new --chain regtest --server http://127.0.0.1:PORT
91
+ python3 -m polarka_agent --dir FOLDER address | balance | history | payments | limits
92
+ python3 -m polarka_agent --dir FOLDER pay ADDRESS 1.5 [--memo TEXT] [--dry-run]
93
+ python3 -m polarka_agent --dir FOLDER pay-many FILE.json
94
+ python3 -m polarka_agent --dir FOLDER received ADDRESS | wait ADDRESS 1.5
95
+ python3 -m polarka_agent --dir FOLDER stamp FILE | stamp --sha256 HEX
96
+ python3 -m polarka_agent --dir FOLDER forget ID
97
+ python3 -m polarka_agent --dir FOLDER mcp
98
+
99
+ Every command prints one JSON object. Amounts are NORTH, written as text. `new --chain main` takes the public
100
+ server of the Northbound project (`https://api.northboundwallet.org`) unless another is named; that server is
101
+ not run by this project. `new` shows the 12 or 24 words once; `--words-file` brings a wallet back.
102
+
103
+ A stamp writes `POLARKA\x01` and a SHA-256 into an output that carries data. The chain is young and its hash
104
+ rate is small: a stamp shows an order of events, it is not proof for a court.
105
+
106
+ For an agent: start `python3 -m polarka_agent --dir FOLDER mcp` as an MCP server over standard input and
107
+ output. Its tools are `north_balance`, `north_address`, `north_received`, `north_wait`, `north_pay`,
108
+ `north_stamp`, `north_payments`, `north_history` and `north_limits`.
109
+
110
+ ## A first coin: the faucet
111
+
112
+ A program that has no coin can ask a faucet for one. It does a small piece of work first (hashing, a few
113
+ seconds of one processor), so that asking a thousand times costs a thousand times as much.
114
+
115
+ python3 -m polarka_agent --dir FOLDER faucet https://ADDRESS-OF-A-FAUCET
116
+
117
+ asks for a little NORTH to a fresh address of the wallet. There is no public faucet yet; when there is one,
118
+ its address will be on polarka.org.
119
+
120
+ Anybody can run one: `faucet-serve --amount 2` hands out 2 NORTH to an address once a day from the wallet in
121
+ FOLDER. What it may give in a day is that wallet's `limits.json`, nothing else, so a faucet is this wallet
122
+ under its own bounds. It keeps the addresses it paid (`faucet.jsonl`) and no internet addresses on disk; it
123
+ asks for no name and no e-mail. It is meant to stand behind a web server that provides HTTPS
124
+ (`--trust-proxy`). The faucet is new: nobody independent has read it, and it has never run in public.
125
+
126
+ ## Something to pay for: postage
127
+
128
+ Whoever runs a web service and wants to keep robots from wearing it out makes them burn processor time for
129
+ nothing today. With postage the caller pays a little NORTH instead, and the one who runs the service gets it.
130
+
131
+ python3 -m polarka_agent --dir FOLDER postage-serve --upstream 127.0.0.1:9000 --price 0.01 --calls 100 --free 20
132
+
133
+ stands before the service on port 9000. A caller without postage gets `402` and what to do, as JSON: ask for
134
+ a quote (`POST /_postage/quote`), pay the price to the address it names, and send the token in the header
135
+ `X-Postage`. Every quote has an address for itself for half an hour, so a payment is told apart without
136
+ anybody proving anything; an address that was not paid serves the next asker. `--free` lets one source make
137
+ some calls a day without postage.
138
+
139
+ Postage is counted in calls. It is not a balance, it is not given back, and the gate never pays from its
140
+ wallet, so the gate holds nobody's coins. Whoever runs a service for payment has the duties of one who does
141
+ (saying who they are, among others); the gate is a tool and takes none of them away. It is new: nobody
142
+ independent has read it, and it has never run in public. There is no asker's command for it yet: a program
143
+ pays the quoted address with `pay` and sends the token itself.
144
+
145
+ ## Code and tests
146
+
147
+ Python 3.9 or later, standard library only. `polarka_agent/keys.py` and `tx.py` hold the keys, addresses, the
148
+ signature hash and signing; they come from the cold address tool
149
+ (github.com/severka-monitor/truenorth-cold-address) and are checked against its published P2QRH test vectors.
150
+ `server.py` is the client for a wallet server, `wallet.py` the wallet, `cli.py` and `mcp.py` the two faces,
151
+ `faucet.py` the faucet and its asker, `postage.py` the postage gate.
152
+
153
+ TN_BIN=/path/to/bin python3 -B -m unittest discover -s tests -t .
154
+
155
+ 79 tests. Those in `test_wallet.py` and `test_cli_mcp.py` run against the official `truenorthd` on regtest
156
+ and a stand-in for a Northbound server (`tests/standin`, copied from the Polarka Wallet's repository); they
157
+ are skipped without the node programs. No test touches a real network.
158
+
159
+ `tests/faults.py` is a test of the tests: it puts one deliberate fault at a time into a copy of the code
160
+ (a limit that is not applied, a day that does not count the payment being made, and so on) and expects the
161
+ tests to fail. It first runs the copy as it stands, and counts a fault as caught only when tests ran and failed. Ten faults
162
+ in the owner's rules. It covers those rules only, not the keys, the signing or the client of the server.
163
+
164
+ ## What is missing
165
+
166
+ - A review by a person. An independent AI reviewer read version 0.1.0.dev0 and found two serious faults (a
167
+ server that lies about a block could lift the day's limit; after two hundred addresses the wallet sent
168
+ change where it did not look). Both are mended here, with tests. Its other findings are listed in
169
+ `REVIEW.md` with what was done about each.
170
+ - More than two hundred addresses of a kind: beyond that the wallet hands out no new address and reuses
171
+ its last change key.
172
+ - More than a first try on the real network.
173
+ - A way to replace a payment that was handed over and waits for a block without end.
174
+ - A node of one's own in place of a wallet server.
175
+ - A history that is exact for a wallet with more than a hundred addresses.
176
+ - Checking a stamp without trusting a server or a node.
177
+
178
+ ## Licence
179
+
180
+ MIT, see `LICENSE`. There is no warranty.
@@ -0,0 +1,158 @@
1
+ # Polarka Agent
2
+
3
+ A wallet for TrueNorth (NORTH) that a program can use: a command line, a Python library, and a server for
4
+ agents that speak the Model Context Protocol (MCP). The keys stay on the machine it runs on. What its
5
+ addresses hold it asks a wallet server with the Northbound API (github.com/nova9/northbound).
6
+
7
+ **State: 0.1.1, an early version.** It was written with an AI model under its author's direction. An
8
+ independent AI reviewer read it and found faults, the serious ones of which are mended (`REVIEW.md`); no
9
+ human security expert has read it. On 17 November 2026 it made its first payments on the real network: two
10
+ small payments went into blocks, and its owner's limits refused what they should (`NO_LIMITS`, `OVER_LIMIT`,
11
+ `OVER_DAY`). That is all the real use it has had. Do not put into it what you cannot lose. It is an independent community project, not a product of the TrueNorth developers or of
12
+ the Northbound project.
13
+
14
+ ## What it is for
15
+
16
+ A program that has a processor and no bank account can earn NORTH by mining and can be paid in it. This
17
+ wallet lets such a program hold coins and pay small amounts by itself, within bounds that a person sets and
18
+ that the tools given to the program cannot change.
19
+
20
+ ## How a program is kept within bounds
21
+
22
+ - Without a file `limits.json` in the wallet's folder the wallet pays nothing. Its owner writes that file by
23
+ hand: `{"per_payment_north": "5", "per_day_north": "20"}`, and if wanted `"allow": [addresses]` and
24
+ `"fee_rate"`. No command and no tool of the MCP server writes or changes it.
25
+ - Every transaction is written into `journal.jsonl` before anything leaves the machine. Lines are only added.
26
+ - The MCP server has no tool that shows the recovery words, changes the limits or forgets a payment.
27
+ - These bounds hold against a program that reaches the wallet through the MCP server only. A program that
28
+ can run commands or write files as the same user can change `limits.json`, move the journal away or read
29
+ the words; against that the wallet does nothing. Give an agent the MCP server, not a shell in that account.
30
+ - A payment counts into its day whatever became of it; only the owner's `forget` takes one out. A payment
31
+ that another one replaced therefore counts twice for a day.
32
+ - What a wallet server says in words is not passed on to the program: a refusal comes as one of a few fixed
33
+ words and an error as its HTTP status.
34
+
35
+ The recovery words are in `wallet.json`, readable by its owner only (mode 600; the program refuses to work
36
+ with a file that others can read). Whoever can read that file can spend. This is a wallet for small amounts
37
+ on a machine its owner controls.
38
+
39
+ ## Paying, and a server that says no
40
+
41
+ The rules are those of the Polarka Wallet for Android, which an independent reviewer looked at.
42
+
43
+ Whoever was shown a signed transaction can keep it and pass it on later, whatever they answered. So a
44
+ payment that the server refused (`kept`) or that got lost (`unknown`) is not forgotten. The next payment is
45
+ built on one of its coins, and only one of the two can ever be in a block. The same payment asked for again
46
+ (same coins, same outputs) is the same transaction and is simply shown to the server once more. While the
47
+ server shows none of the coins of such a payment, the wallet pays nothing at all, until its owner has looked
48
+ at the wallet through another server or a node and forgets the payment by hand (`forget`).
49
+
50
+ A wallet server sees the wallet's addresses together and the machine's internet address. It can show a false
51
+ balance or hold a payment back. It can stop the wallet until its owner acts (by refusing a payment and then
52
+ hiding its coins), and it can keep one command waiting for a long time by answering slowly. It cannot take
53
+ coins. A program is not shown the server's own words: why a node refused a payment comes as one of a few
54
+ fixed words (`FEE_TOO_LOW`, `INPUTS_GONE`, `OTHER`, ...), an error as its HTTP status, and a receiver in the
55
+ history only if it has the shape of an address. The words themselves appear at the command line alone,
56
+ under `server_said_untrusted`, for the owner.
57
+
58
+ ## Installing
59
+
60
+ pip install polarka-agent
61
+
62
+ That gives the command `polarka-agent`, which is the same as `python3 -m polarka_agent`. It needs Python 3.9
63
+ or later on Linux or macOS and nothing besides; it does not run on Windows. The package on PyPI is built from
64
+ this repository at the tag of its version.
65
+
66
+ ## Commands
67
+
68
+ python3 -m polarka_agent --dir FOLDER new --chain regtest --server http://127.0.0.1:PORT
69
+ python3 -m polarka_agent --dir FOLDER address | balance | history | payments | limits
70
+ python3 -m polarka_agent --dir FOLDER pay ADDRESS 1.5 [--memo TEXT] [--dry-run]
71
+ python3 -m polarka_agent --dir FOLDER pay-many FILE.json
72
+ python3 -m polarka_agent --dir FOLDER received ADDRESS | wait ADDRESS 1.5
73
+ python3 -m polarka_agent --dir FOLDER stamp FILE | stamp --sha256 HEX
74
+ python3 -m polarka_agent --dir FOLDER forget ID
75
+ python3 -m polarka_agent --dir FOLDER mcp
76
+
77
+ Every command prints one JSON object. Amounts are NORTH, written as text. `new --chain main` takes the public
78
+ server of the Northbound project (`https://api.northboundwallet.org`) unless another is named; that server is
79
+ not run by this project. `new` shows the 12 or 24 words once; `--words-file` brings a wallet back.
80
+
81
+ A stamp writes `POLARKA\x01` and a SHA-256 into an output that carries data. The chain is young and its hash
82
+ rate is small: a stamp shows an order of events, it is not proof for a court.
83
+
84
+ For an agent: start `python3 -m polarka_agent --dir FOLDER mcp` as an MCP server over standard input and
85
+ output. Its tools are `north_balance`, `north_address`, `north_received`, `north_wait`, `north_pay`,
86
+ `north_stamp`, `north_payments`, `north_history` and `north_limits`.
87
+
88
+ ## A first coin: the faucet
89
+
90
+ A program that has no coin can ask a faucet for one. It does a small piece of work first (hashing, a few
91
+ seconds of one processor), so that asking a thousand times costs a thousand times as much.
92
+
93
+ python3 -m polarka_agent --dir FOLDER faucet https://ADDRESS-OF-A-FAUCET
94
+
95
+ asks for a little NORTH to a fresh address of the wallet. There is no public faucet yet; when there is one,
96
+ its address will be on polarka.org.
97
+
98
+ Anybody can run one: `faucet-serve --amount 2` hands out 2 NORTH to an address once a day from the wallet in
99
+ FOLDER. What it may give in a day is that wallet's `limits.json`, nothing else, so a faucet is this wallet
100
+ under its own bounds. It keeps the addresses it paid (`faucet.jsonl`) and no internet addresses on disk; it
101
+ asks for no name and no e-mail. It is meant to stand behind a web server that provides HTTPS
102
+ (`--trust-proxy`). The faucet is new: nobody independent has read it, and it has never run in public.
103
+
104
+ ## Something to pay for: postage
105
+
106
+ Whoever runs a web service and wants to keep robots from wearing it out makes them burn processor time for
107
+ nothing today. With postage the caller pays a little NORTH instead, and the one who runs the service gets it.
108
+
109
+ python3 -m polarka_agent --dir FOLDER postage-serve --upstream 127.0.0.1:9000 --price 0.01 --calls 100 --free 20
110
+
111
+ stands before the service on port 9000. A caller without postage gets `402` and what to do, as JSON: ask for
112
+ a quote (`POST /_postage/quote`), pay the price to the address it names, and send the token in the header
113
+ `X-Postage`. Every quote has an address for itself for half an hour, so a payment is told apart without
114
+ anybody proving anything; an address that was not paid serves the next asker. `--free` lets one source make
115
+ some calls a day without postage.
116
+
117
+ Postage is counted in calls. It is not a balance, it is not given back, and the gate never pays from its
118
+ wallet, so the gate holds nobody's coins. Whoever runs a service for payment has the duties of one who does
119
+ (saying who they are, among others); the gate is a tool and takes none of them away. It is new: nobody
120
+ independent has read it, and it has never run in public. There is no asker's command for it yet: a program
121
+ pays the quoted address with `pay` and sends the token itself.
122
+
123
+ ## Code and tests
124
+
125
+ Python 3.9 or later, standard library only. `polarka_agent/keys.py` and `tx.py` hold the keys, addresses, the
126
+ signature hash and signing; they come from the cold address tool
127
+ (github.com/severka-monitor/truenorth-cold-address) and are checked against its published P2QRH test vectors.
128
+ `server.py` is the client for a wallet server, `wallet.py` the wallet, `cli.py` and `mcp.py` the two faces,
129
+ `faucet.py` the faucet and its asker, `postage.py` the postage gate.
130
+
131
+ TN_BIN=/path/to/bin python3 -B -m unittest discover -s tests -t .
132
+
133
+ 79 tests. Those in `test_wallet.py` and `test_cli_mcp.py` run against the official `truenorthd` on regtest
134
+ and a stand-in for a Northbound server (`tests/standin`, copied from the Polarka Wallet's repository); they
135
+ are skipped without the node programs. No test touches a real network.
136
+
137
+ `tests/faults.py` is a test of the tests: it puts one deliberate fault at a time into a copy of the code
138
+ (a limit that is not applied, a day that does not count the payment being made, and so on) and expects the
139
+ tests to fail. It first runs the copy as it stands, and counts a fault as caught only when tests ran and failed. Ten faults
140
+ in the owner's rules. It covers those rules only, not the keys, the signing or the client of the server.
141
+
142
+ ## What is missing
143
+
144
+ - A review by a person. An independent AI reviewer read version 0.1.0.dev0 and found two serious faults (a
145
+ server that lies about a block could lift the day's limit; after two hundred addresses the wallet sent
146
+ change where it did not look). Both are mended here, with tests. Its other findings are listed in
147
+ `REVIEW.md` with what was done about each.
148
+ - More than two hundred addresses of a kind: beyond that the wallet hands out no new address and reuses
149
+ its last change key.
150
+ - More than a first try on the real network.
151
+ - A way to replace a payment that was handed over and waits for a block without end.
152
+ - A node of one's own in place of a wallet server.
153
+ - A history that is exact for a wallet with more than a hundred addresses.
154
+ - Checking a stamp without trusting a server or a node.
155
+
156
+ ## Licence
157
+
158
+ MIT, see `LICENSE`. There is no warranty.
@@ -0,0 +1,28 @@
1
+ # What an independent reviewer found, and what was done
2
+
3
+ An independent AI reviewer, which had not seen the code being written, read version 0.1.0.dev0 (commit
4
+ `e30816c`). It is not a human security expert, and a review of this kind finds some faults and does not show
5
+ that there are no others. Its report is in `review/report-0.1.0.dev0.md`, unchanged. Its verdict: the source
6
+ may be public as a clearly labelled work in progress; it is not to be used with real coins yet.
7
+
8
+ | ID | Severity | Finding in short | State |
9
+ |---|---|---|---|
10
+ | F1 | High | A server that falsely reports a small payment as in a block made the wallet drop the refused payment it stood against from the day's sum; repeated, the day's limit did not hold | Mended: a payment counts into its day whatever became of it, only the owner's `forget` takes one out. Test: `test_a_server_that_lies_about_a_block_does_not_free_the_day` |
11
+ | F2 | High | The wallet looks at 200 keys of a kind, yet sent change to key 200 and handed out address 200 | Mended: change reuses the last key that is looked at, and no address beyond is handed out (`TOO_MANY_ADDRESSES`). Two tests |
12
+ | F3 | Medium | Text chosen by the server reaches the agent through MCP results | Mended: a refusal is passed on as one of a few fixed words, an error as its HTTP status, and a receiver that has not the shape of an address is refused; the words are shown at the command line only. Two tests. A memo (F17) is still shown as it was given |
13
+ | F4 | Medium | The bounds hold against the MCP tools only, not against a program with a shell or file access as the same user | By design; the README now says so |
14
+ | F5 | Medium | One output of amount 0 on an address of the wallet stopped every command | Mended: such an output is no coin and is passed over. Test |
15
+ | F6 | Low | A payment that did not go through and is asked for again after 24 hours is not counted in that day | Open |
16
+ | F7 | Low | "In a block" is final at one confirmation | Open |
17
+ | F8 | Low | A lying server can stop the wallet until its owner acts and can hold the folder's lock for long | Open; the README now says so |
18
+ | F9 | Low | A deeply nested JSON line ends the MCP server | Open |
19
+ | F10 | Low | Some inputs ended the command line with a traceback | Mended: whatever else goes wrong is one JSON object, `INTERNAL` |
20
+ | F11 | Low | Journal, state, lock and limits are readable by others on the machine | Open |
21
+ | F12 | Low | The test of the tests counted any failing run as caught and had no run of the unchanged code | Mended: it runs the code as it stands first, and counts only tests that ran and failed |
22
+ | F13 | Low | `received` and `wait` report what sits unspent on an address, not that one payment arrived | Open |
23
+ | F14 | Note | The day is counted by the machine's clock and the journal | Open, by design for now |
24
+ | F15 | Note | Plain http is allowed to private ranges | Open |
25
+ | F16 | Note | The wording about a stamp's fee holds at the default fee rate only | Open |
26
+ | F17 | Note | A memo is stored and later shown to agents unfiltered | Open |
27
+
28
+ Nothing here has been checked by the reviewer again after the mending.
@@ -0,0 +1,2 @@
1
+ """Polarka Agent: a TrueNorth (NORTH) wallet that a program can use."""
2
+ __version__ = "0.1.1"
@@ -0,0 +1,3 @@
1
+ from polarka_agent.cli import main
2
+
3
+ main()
@@ -0,0 +1,197 @@
1
+ """polarka-agent: a TrueNorth (NORTH) wallet that a program can use. The command line.
2
+
3
+ Every command prints one JSON object. A command that is refused prints {"error": KIND, "message": ...} and
4
+ ends with status 2; a server that cannot be believed or reached ends with status 3.
5
+ """
6
+ import argparse
7
+ import hashlib
8
+ import json
9
+ import os
10
+ import sys
11
+ import time
12
+
13
+ from . import __version__
14
+ from .keys import BadInput
15
+ from .server import ServerError
16
+ from .wallet import Refused, Wallet, north, units
17
+
18
+ DEFAULT_SERVER = "https://api.northboundwallet.org" # the public server of the Northbound project; not run by this project
19
+
20
+
21
+ def _amounts(result):
22
+ """Base units to NORTH, for the fields that are amounts."""
23
+ for name in ("spendable", "set_aside", "unripe", "amount"):
24
+ if isinstance(result.get(name), int) and not isinstance(result.get(name), bool):
25
+ result[name] = north(result[name])
26
+ for line in result.get("lines", []):
27
+ for name in ("received", "sent", "fee"):
28
+ if isinstance(line.get(name), int):
29
+ line[name] = north(line[name])
30
+ return result
31
+
32
+
33
+ def wait_for(wallet, address, amount, confirmations=1, timeout=600, every=15, sleep=time.sleep, clock=time.monotonic):
34
+ """Looks at one of the wallet's addresses until it holds the amount that deep, or the time is over."""
35
+ until = clock() + timeout
36
+ while True:
37
+ seen = wallet.received(address)
38
+ if seen["amount"] >= amount and seen["confirmations"] >= confirmations:
39
+ return dict(_amounts(seen), paid=True)
40
+ if clock() + every > until:
41
+ return dict(_amounts(seen), paid=False)
42
+ sleep(every)
43
+
44
+
45
+ def run(argv=None, out=sys.stdout):
46
+ p = argparse.ArgumentParser(prog="polarka-agent", description="A TrueNorth (NORTH) wallet that a program can use.")
47
+ p.add_argument("--version", action="version", version=__version__)
48
+ p.add_argument("--dir", default=os.environ.get("POLARKA_AGENT_DIR", "~/.polarka-agent/default"), help="the wallet's folder")
49
+ sub = p.add_subparsers(dest="cmd", required=True)
50
+ c = sub.add_parser("new", help="make a wallet, or bring one back from its words")
51
+ c.add_argument("--chain", required=True, choices=("main", "regtest"))
52
+ c.add_argument("--server", help="the wallet server (default on main: %s)" % DEFAULT_SERVER)
53
+ c.add_argument("--words-file", help="a file with the 12 or 24 words of a wallet to bring back")
54
+ c.add_argument("--twelve", action="store_true", help="12 words in place of 24")
55
+ sub.add_parser("address", help="a fresh address to be paid to")
56
+ sub.add_parser("balance")
57
+ sub.add_parser("history")
58
+ sub.add_parser("payments", help="what this wallet paid and what became of it")
59
+ sub.add_parser("limits", help="what the owner lets the wallet pay by itself")
60
+ c = sub.add_parser("received", help="what sits on one of the wallet's addresses")
61
+ c.add_argument("address")
62
+ c = sub.add_parser("wait", help="wait until an address of the wallet holds an amount")
63
+ c.add_argument("address")
64
+ c.add_argument("amount")
65
+ c.add_argument("--confirmations", type=int, default=1)
66
+ c.add_argument("--timeout", type=int, default=600)
67
+ c = sub.add_parser("pay")
68
+ c.add_argument("address")
69
+ c.add_argument("amount", help="NORTH, for example 1.5")
70
+ c.add_argument("--memo")
71
+ c.add_argument("--dry-run", action="store_true")
72
+ c = sub.add_parser("pay-many", help="several payments in one transaction")
73
+ c.add_argument("file", help='a JSON list: [{"address": "...", "amount": "1.5"}, ...]')
74
+ c.add_argument("--memo")
75
+ c.add_argument("--dry-run", action="store_true")
76
+ c = sub.add_parser("stamp", help="write the SHA-256 of a file into the chain")
77
+ c.add_argument("file", nargs="?")
78
+ c.add_argument("--sha256", help="the SHA-256 itself, 64 hex characters, in place of a file")
79
+ c.add_argument("--memo")
80
+ c.add_argument("--dry-run", action="store_true")
81
+ c = sub.add_parser("forget", help="the owner's word that a payment which did not go through stands against nothing any more")
82
+ c.add_argument("id")
83
+ sub.add_parser("mcp", help="serve the wallet to an agent over the Model Context Protocol (standard input and output)")
84
+ c = sub.add_parser("faucet", help="ask a faucet for a first coin, to a fresh address of this wallet")
85
+ c.add_argument("url")
86
+ c = sub.add_parser("postage-serve", help="be a gate before a web service that lets through who paid postage to this wallet")
87
+ c.add_argument("--upstream", required=True, help="the service behind the gate, host:port")
88
+ c.add_argument("--price", required=True, help="NORTH for one lot of calls")
89
+ c.add_argument("--calls", type=int, default=100, help="calls in one lot")
90
+ c.add_argument("--free", type=int, default=0, help="calls a day that one source may make without postage")
91
+ c.add_argument("--listen", default="127.0.0.1:8670")
92
+ c.add_argument("--trust-proxy", action="store_true", help="take the caller's address from X-Forwarded-For")
93
+ c = sub.add_parser("faucet-serve", help="be a faucet: hand out a little from this wallet, within its limits.json")
94
+ c.add_argument("--amount", required=True, help="NORTH given to one address")
95
+ c.add_argument("--listen", default="127.0.0.1:8660")
96
+ c.add_argument("--bits", type=int, default=20, help="zero bits of work asked for when the faucet is quiet")
97
+ c.add_argument("--trust-proxy", action="store_true", help="take the asker's address from X-Forwarded-For")
98
+ a = p.parse_args(argv)
99
+ folder = os.path.expanduser(a.dir)
100
+
101
+ def show(result, status=0):
102
+ out.write(json.dumps(result, indent=1) + "\n")
103
+ return status
104
+
105
+ try:
106
+ if a.cmd == "new":
107
+ server = a.server or (DEFAULT_SERVER if a.chain == "main" else None)
108
+ if server is None:
109
+ raise Refused("SERVER", "name the wallet server with --server")
110
+ words = None
111
+ if a.words_file:
112
+ with open(os.path.expanduser(a.words_file)) as f:
113
+ words = f.read()
114
+ made = Wallet.create(folder, a.chain, server, words, 12 if a.twelve else 24)
115
+ first = Wallet(folder).account.address(0, 0)
116
+ if words is not None:
117
+ return show({"folder": folder, "first_address": first, "brought_back": True})
118
+ return show({"folder": folder, "first_address": first, "words": made,
119
+ "note": "Write the words on paper now. They are the wallet. They are also in wallet.json, which only you may read; "
120
+ "whoever reads that file can spend. The wallet pays nothing until you write limits.json."})
121
+ wallet = Wallet(folder)
122
+ if a.cmd == "mcp":
123
+ from .mcp import serve
124
+ return serve(wallet)
125
+ if a.cmd == "address":
126
+ return show({"address": wallet.fresh_address()})
127
+ if a.cmd == "faucet":
128
+ from .faucet import ask
129
+ return show(ask(a.url, wallet.fresh_address()))
130
+ if a.cmd == "postage-serve":
131
+ from .postage import serve as postage_serve
132
+ return postage_serve(wallet, a.upstream, units(a.price), a.calls, a.listen, a.free, a.trust_proxy)
133
+ if a.cmd == "faucet-serve":
134
+ from .faucet import serve as faucet_serve
135
+ if not 10 <= a.bits <= 30:
136
+ raise Refused("INPUT", "--bits is 10 to 30")
137
+ return faucet_serve(wallet, units(a.amount), a.listen, a.trust_proxy, a.bits)
138
+ if a.cmd == "balance":
139
+ return show(_amounts(wallet.balance()))
140
+ if a.cmd == "history":
141
+ return show(_amounts(wallet.history()))
142
+ if a.cmd == "payments":
143
+ return show({"payments": wallet.payments()})
144
+ if a.cmd == "limits":
145
+ return show(wallet.limits_shown())
146
+ if a.cmd == "received":
147
+ return show(_amounts(wallet.received(a.address)))
148
+ if a.cmd == "wait":
149
+ return show(wait_for(wallet, a.address, units(a.amount), a.confirmations, a.timeout))
150
+ if a.cmd == "pay":
151
+ return show(wallet.pay([(a.address, units(a.amount))], a.memo, a.dry_run))
152
+ if a.cmd == "pay-many":
153
+ with open(os.path.expanduser(a.file)) as f:
154
+ wanted = json.load(f)
155
+ if type(wanted) is not list or not all(type(w) is dict and set(w) == {"address", "amount"} for w in wanted):
156
+ raise Refused("FILE", 'the file is a JSON list of {"address": ..., "amount": "1.5"}')
157
+ return show(wallet.pay([(w["address"], units(w["amount"])) for w in wanted], a.memo, a.dry_run))
158
+ if a.cmd == "stamp":
159
+ if bool(a.file) == bool(a.sha256):
160
+ raise Refused("DIGEST", "name a file or give --sha256, one of the two")
161
+ if a.file:
162
+ h = hashlib.sha256()
163
+ with open(os.path.expanduser(a.file), "rb") as f:
164
+ for piece in iter(lambda: f.read(1 << 20), b""):
165
+ h.update(piece)
166
+ digest = h.digest()
167
+ else:
168
+ try:
169
+ digest = bytes.fromhex(a.sha256)
170
+ except ValueError:
171
+ raise Refused("DIGEST", "a SHA-256 is 64 hex characters")
172
+ return show(dict(wallet.stamp(digest, a.memo, a.dry_run), sha256=digest.hex()))
173
+ if a.cmd == "forget":
174
+ wallet.forget(a.id)
175
+ return show({"forgotten": a.id})
176
+ except Refused as e:
177
+ return show({"error": e.kind, "message": str(e)}, 2)
178
+ except BadInput as e:
179
+ return show({"error": "INPUT", "message": str(e)}, 2)
180
+ except ServerError as e:
181
+ shown = {"error": "SERVER", "status": e.status, "kind": e.kind, "message": str(e)}
182
+ if e.said:
183
+ shown["server_said_untrusted"] = e.said # for the owner at the command line; the MCP server never shows it
184
+ return show(shown, 3)
185
+ except OSError as e:
186
+ return show({"error": "FILE", "message": "%s: %s" % (type(e).__name__, e.strerror or e)}, 2)
187
+ except Exception as e: # whatever else: one JSON object, never a traceback with what it may hold
188
+ return show({"error": "INTERNAL", "message": type(e).__name__}, 4)
189
+ return 1
190
+
191
+
192
+ def main():
193
+ sys.exit(run())
194
+
195
+
196
+ if __name__ == "__main__":
197
+ main()