polarka-agent 0.1.1__py3-none-any.whl
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/__init__.py +2 -0
- polarka_agent/__main__.py +3 -0
- polarka_agent/cli.py +197 -0
- polarka_agent/english.txt +2048 -0
- polarka_agent/faucet.py +283 -0
- polarka_agent/keys.py +318 -0
- polarka_agent/mcp.py +145 -0
- polarka_agent/postage.py +223 -0
- polarka_agent/server.py +449 -0
- polarka_agent/tx.py +178 -0
- polarka_agent/wallet.py +479 -0
- polarka_agent-0.1.1.dist-info/METADATA +180 -0
- polarka_agent-0.1.1.dist-info/RECORD +16 -0
- polarka_agent-0.1.1.dist-info/WHEEL +4 -0
- polarka_agent-0.1.1.dist-info/entry_points.txt +2 -0
- polarka_agent-0.1.1.dist-info/licenses/LICENSE +21 -0
polarka_agent/cli.py
ADDED
|
@@ -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()
|