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.
- polarka_agent-0.1.1/.gitignore +5 -0
- polarka_agent-0.1.1/LICENSE +21 -0
- polarka_agent-0.1.1/PKG-INFO +180 -0
- polarka_agent-0.1.1/README.md +158 -0
- polarka_agent-0.1.1/REVIEW.md +28 -0
- polarka_agent-0.1.1/polarka_agent/__init__.py +2 -0
- polarka_agent-0.1.1/polarka_agent/__main__.py +3 -0
- polarka_agent-0.1.1/polarka_agent/cli.py +197 -0
- polarka_agent-0.1.1/polarka_agent/english.txt +2048 -0
- polarka_agent-0.1.1/polarka_agent/faucet.py +283 -0
- polarka_agent-0.1.1/polarka_agent/keys.py +318 -0
- polarka_agent-0.1.1/polarka_agent/mcp.py +145 -0
- polarka_agent-0.1.1/polarka_agent/postage.py +223 -0
- polarka_agent-0.1.1/polarka_agent/server.py +449 -0
- polarka_agent-0.1.1/polarka_agent/tx.py +178 -0
- polarka_agent-0.1.1/polarka_agent/wallet.py +479 -0
- polarka_agent-0.1.1/pyproject.toml +52 -0
- polarka_agent-0.1.1/review/report-0.1.0.dev0.md +318 -0
- polarka_agent-0.1.1/tests/__init__.py +0 -0
- polarka_agent-0.1.1/tests/bench.py +96 -0
- polarka_agent-0.1.1/tests/fake.py +84 -0
- polarka_agent-0.1.1/tests/faults.py +77 -0
- polarka_agent-0.1.1/tests/p2qrh-test-vectors.json +260 -0
- polarka_agent-0.1.1/tests/standin/northbound_standin.py +654 -0
- polarka_agent-0.1.1/tests/test_cli_mcp.py +217 -0
- polarka_agent-0.1.1/tests/test_faucet.py +128 -0
- polarka_agent-0.1.1/tests/test_keys_tx.py +211 -0
- polarka_agent-0.1.1/tests/test_postage.py +134 -0
- polarka_agent-0.1.1/tests/test_server.py +283 -0
- polarka_agent-0.1.1/tests/test_wallet.py +337 -0
- polarka_agent-0.1.1/tests/test_wallet_rules.py +266 -0
|
@@ -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,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()
|