stack.py (20014B)
1 # This file is part of GNU Taler 2 # (C) 2026 Taler Systems S.A. 3 # 4 # GNU Taler is free software; you can redistribute it and/or modify it under the 5 # terms of the GNU General Public License as published by the Free Software 6 # Foundation; either version 3, or (at your option) any later version. 7 # 8 # GNU Taler is distributed in the hope that it will be useful, but WITHOUT ANY 9 # WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR 10 # A PARTICULAR PURPOSE. See the GNU General Public License for more details. 11 # 12 # You should have received a copy of the GNU General Public License along with 13 # GNU Taler; see the file COPYING. If not, see <http://www.gnu.org/licenses/> 14 """Host-side clients for the simulator's Taler stack. 15 16 Everything the wallet's counterparties do happens here over HTTP: the bank 17 (libeufin corebank) registers customers, opens and confirms withdrawals and 18 reports balances; the merchant creates instances, orders and refunds. Keeping 19 the counterparties on the host makes a scenario deterministic — the only thing 20 being explored is the wallet. 21 """ 22 23 from __future__ import annotations 24 25 import base64 26 import json 27 import os 28 from pathlib import Path 29 from urllib.parse import quote 30 import uuid 31 import urllib.error 32 import urllib.request 33 from dataclasses import dataclass 34 from typing import Any, Optional 35 36 DEFAULT_ENV = "/opt/taler-sim/run/stack/env.json" 37 38 39 class HttpError(RuntimeError): 40 def __init__(self, status: int, body: str, url: str): 41 super().__init__(f"HTTP {status} for {url}: {body[:300]}") 42 self.status = status 43 self.body = body 44 45 46 def _request( 47 url: str, 48 method: str = "GET", 49 payload: Any = None, 50 auth: Optional[tuple[str, str]] = None, 51 timeout: int = 30, 52 ) -> Any: 53 data = None 54 headers = {"Accept": "application/json"} 55 if payload is not None: 56 data = json.dumps(payload).encode() 57 headers["Content-Type"] = "application/json" 58 if auth: 59 token = base64.b64encode(f"{auth[0]}:{auth[1]}".encode()).decode() 60 headers["Authorization"] = f"Basic {token}" 61 req = urllib.request.Request(url, data=data, headers=headers, method=method) 62 try: 63 with urllib.request.urlopen(req, timeout=timeout) as resp: 64 body = resp.read().decode() 65 except urllib.error.HTTPError as e: 66 raise HttpError(e.code, e.read().decode(errors="replace"), url) from None 67 if not body.strip(): 68 return None 69 try: 70 return json.loads(body) 71 except json.JSONDecodeError: 72 return body 73 74 75 @dataclass 76 class Env: 77 """The URLs and credentials stack.sh wrote out.""" 78 79 exchange: str 80 merchant: str 81 bank: str 82 donau: str 83 auditor: str 84 currency: str 85 # Only there when backend/exchange2.sh is running beside the stack. 86 exchange2: str | None = None 87 88 @classmethod 89 def load(cls, path: str = DEFAULT_ENV) -> "Env": 90 with open(path) as f: 91 d = json.load(f) 92 return cls( 93 exchange=d["exchange"], merchant=d["merchant"], bank=d["bank"], 94 donau=d["donau"], auditor=d["auditor"], currency=d["currency"], 95 exchange2=d.get("exchange2"), 96 ) 97 98 99 class Bank: 100 """libeufin-bank corebank API.""" 101 102 def __init__(self, base_url: str): 103 self.base = base_url.rstrip("/") 104 105 def config(self) -> Any: 106 return _request(f"{self.base}/config") 107 108 def register(self, username: str, password: str, name: str) -> Any: 109 # Passwords shorter than 8 characters are rejected by the bank. 110 return _request(f"{self.base}/accounts", "POST", 111 {"username": username, "password": password, "name": name}) 112 113 def account(self, username: str, password: str) -> Any: 114 return _request(f"{self.base}/accounts/{username}", auth=(username, password)) 115 116 def balance(self, username: str, password: str) -> str: 117 acc = self.account(username, password) 118 bal = acc["balance"] 119 sign = "-" if bal["credit_debit_indicator"] == "debit" else "" 120 return f"{sign}{bal['amount']}" 121 122 def payto(self, username: str, password: str) -> str: 123 return self.account(username, password)["payto_uri"] 124 125 def create_withdrawal(self, username: str, password: str, amount: str) -> Any: 126 """Open a withdrawal operation; returns withdrawal_id + taler_withdraw_uri. 127 128 A round spends more than the registration bonus, so an exhausted 129 account is topped up and the request retried once rather than failing 130 the scenario with something that looks like a wallet bug. 131 """ 132 try: 133 return _request(f"{self.base}/accounts/{username}/withdrawals", "POST", 134 {"amount": amount}, auth=(username, password)) 135 except HttpError as e: 136 if e.status != 409 or "5102" not in e.body: 137 raise 138 self.top_up(username, "EUR:2000") 139 return _request(f"{self.base}/accounts/{username}/withdrawals", "POST", 140 {"amount": amount}, auth=(username, password)) 141 142 def withdrawal_status(self, wid: str) -> Any: 143 return _request(f"{self.base}/withdrawals/{wid}") 144 145 def confirm_withdrawal(self, username: str, password: str, wid: str) -> Any: 146 """The step a human would take in the bank's own UI.""" 147 return _request(f"{self.base}/accounts/{username}/withdrawals/{wid}/confirm", 148 "POST", {}, auth=(username, password)) 149 150 def abort_withdrawal(self, username: str, password: str, wid: str) -> Any: 151 return _request(f"{self.base}/accounts/{username}/withdrawals/{wid}/abort", 152 "POST", {}, auth=(username, password)) 153 154 ADMIN = ("admin", "secret-password") # set by taler-unified-setup.sh 155 156 def top_up(self, username: str, amount: str = "EUR:200") -> Any: 157 """Credit a customer from the admin account. 158 159 Scenario runs spend the registration bonus quickly, and an exhausted 160 bank account looks just like a wallet bug in the logs, so accounts get 161 topped up between iterations. Admin may read any account, so the 162 customer's own password is not needed. 163 """ 164 account = _request(f"{self.base}/accounts/{username}", auth=self.ADMIN) 165 payto = account["payto_uri"] 166 joiner = "&" if "?" in payto else "?" 167 return _request( 168 f"{self.base}/accounts/{self.ADMIN[0]}/transactions", "POST", 169 {"payto_uri": f"{payto}{joiner}amount={amount}&message=simulator top up"}, 170 auth=self.ADMIN, 171 ) 172 173 def transfer(self, username: str, password: str, to_payto: str, 174 amount: str, subject: str) -> Any: 175 """Pay from one customer account to any payto URI, with a subject. 176 177 This is how a manual (not bank-integrated) withdrawal is completed: the 178 wallet shows a subject -- the reserve public key -- and the user makes 179 the transfer in their own bank. The exchange's wirewatch then sees the 180 credit and the withdrawal goes through. 181 """ 182 joiner = "&" if "?" in to_payto else "?" 183 return _request( 184 f"{self.base}/accounts/{username}/transactions", "POST", 185 {"payto_uri": f"{to_payto}{joiner}amount={amount}" 186 f"&message={quote(subject)}"}, 187 auth=(username, password), 188 ) 189 190 def transactions(self, username: str, password: str) -> Any: 191 return _request(f"{self.base}/accounts/{username}/transactions", 192 auth=(username, password)) 193 194 195 class Merchant: 196 """taler-merchant backend, private and management APIs.""" 197 198 def __init__(self, base_url: str, instance: str = "sim"): 199 self.base = base_url.rstrip("/") 200 self.instance = instance 201 202 @property 203 def private(self) -> str: 204 return f"{self.base}/instances/{self.instance}/private" 205 206 def config(self) -> Any: 207 return _request(f"{self.base}/config") 208 209 def exists(self) -> bool: 210 try: 211 _request(f"{self.base}/instances/{self.instance}/config") 212 return True 213 except HttpError: 214 return False 215 216 def create_instance(self, name: str = "Simulator Shop") -> None: 217 """Idempotent. 218 219 The management API is only open while the instance does not exist yet: 220 a second POST for the same id is an update and comes back 401 (or 409), 221 so an existing instance is probed for first and both codes tolerated. 222 """ 223 if self.exists(): 224 return 225 try: 226 _request(f"{self.base}/management/instances", "POST", { 227 "id": self.instance, 228 "name": name, 229 "auth": {"method": "external"}, 230 "address": {}, 231 "jurisdiction": {}, 232 "use_stefan": True, 233 "default_wire_transfer_delay": {"d_us": 3600 * 1000 * 1000}, 234 "default_pay_delay": {"d_us": 3600 * 1000 * 1000}, 235 }) 236 except HttpError as e: 237 if e.status not in (401, 409): 238 raise 239 240 def add_account(self, payto_uri: str) -> Any: 241 """Idempotent: re-adding the same account comes back 409.""" 242 try: 243 return _request(f"{self.private}/accounts", "POST", {"payto_uri": payto_uri}) 244 except HttpError as e: 245 if e.status != 409: 246 raise 247 return None 248 249 def create_otp_device(self, device_id: str = "simpos", 250 key: str = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567", 251 algorithm: str = "TOTP_WITHOUT_PRICE") -> Any: 252 """A point-of-sale confirmation device. Idempotent. 253 254 An order that names one gets a `pos_confirmation` in its pay reply, 255 which is the only thing that makes the wallet show its TOTP screen. 256 The key is RFC 3548 base32, not Crockford. 257 """ 258 body = { 259 "otp_device_id": device_id, 260 "otp_device_description": "Simulator point of sale", 261 "otp_algorithm": algorithm, 262 "otp_key": key, 263 "otp_ctr": 0, 264 } 265 try: 266 return _request(f"{self.private}/otp-devices", "POST", body) 267 except HttpError as e: 268 if e.status != 409: 269 raise 270 return None 271 272 def create_order( 273 self, 274 amount: str, 275 summary: str = "Simulator order", 276 fulfillment_url: str | None = None, 277 otp_id: str | None = None, 278 **order_extra: Any, 279 ) -> dict: 280 """Create an order and return it with its taler://pay URI. 281 282 Each order gets its own fulfillment URL unless one is given: the 283 wallet treats a second order with a fulfillment URL it has already 284 paid for as a repurchase and answers "You've already paid for this 285 purchase", which silently skips the payment a scenario was testing. 286 """ 287 if fulfillment_url is None: 288 fulfillment_url = ( 289 "https://example.com/fulfillment/" 290 f"{uuid.uuid4().hex[:16]}" 291 ) 292 order = { 293 "amount": amount, 294 "summary": summary, 295 "fulfillment_url": fulfillment_url, 296 **order_extra, 297 } 298 # otp_id is a sibling of "order", not a field of it. 299 body: dict = {"order": order} 300 if otp_id is not None: 301 body["otp_id"] = otp_id 302 res = _request(f"{self.private}/orders", "POST", body) 303 status = self.order_status(res["order_id"], res.get("token")) 304 return { 305 "order_id": res["order_id"], 306 "token": res.get("token"), 307 "pay_uri": status.get("taler_pay_uri"), 308 "status": status, 309 } 310 311 def create_token_family(self, slug: str = "simdiscount", 312 kind: str = "discount", 313 name: str = "Simulator discount") -> Any: 314 """A token family, so orders can issue and demand tokens. 315 316 Discount tokens are what the wallet shows under "Discounts"; nothing 317 reaches that screen until an order issues one. 318 """ 319 body = { 320 "slug": slug, 321 "name": name, 322 "description": f"{kind} tokens issued by the simulator", 323 "duration": {"d_us": 365 * 24 * 3600 * 1000 * 1000}, 324 "validity_granularity": {"d_us": 24 * 3600 * 1000 * 1000}, 325 "start_offset": {"d_us": 0}, 326 "kind": kind, 327 } 328 try: 329 return _request(f"{self.private}/tokenfamilies", "POST", body) 330 except HttpError as e: 331 if e.status != 409: 332 raise 333 return None 334 335 def create_v1_order(self, choices: list[dict], summary: str = "Simulator v1 order", 336 fulfillment_url: str = "https://example.com/fulfillment", 337 **extra: Any) -> dict: 338 """A version 1 ("mumimo") order: several choices, with token inputs 339 and outputs.""" 340 order = { 341 "version": 1, 342 "summary": summary, 343 "fulfillment_url": fulfillment_url, 344 "choices": choices, 345 **extra, 346 } 347 res = _request(f"{self.private}/orders", "POST", {"order": order}) 348 status = self.order_status(res["order_id"], res.get("token")) 349 return { 350 "order_id": res["order_id"], 351 "token": res.get("token"), 352 "pay_uri": status.get("taler_pay_uri"), 353 "status": status, 354 } 355 356 @staticmethod 357 def token_output(slug: str = "simdiscount", count: int = 1) -> dict: 358 return {"type": "token", "token_family_slug": slug, "count": count, 359 "key_index": 0} 360 361 @staticmethod 362 def token_input(slug: str = "simdiscount", count: int = 1) -> dict: 363 return {"type": "token", "token_family_slug": slug, "count": count} 364 365 def create_template(self, template_id: str = "simtemplate", 366 amount: str = "EUR:1") -> Any: 367 """A reusable order template, paid through a taler://pay-template URI.""" 368 body = { 369 "template_id": template_id, 370 "template_description": "Simulator template", 371 "template_contract": { 372 "amount": amount, 373 "minimum_age": 0, 374 "pay_duration": {"d_us": 3600 * 1000 * 1000}, 375 }, 376 } 377 try: 378 return _request(f"{self.private}/templates", "POST", body) 379 except HttpError as e: 380 if e.status != 409: 381 raise 382 return None 383 384 def order_status(self, order_id: str, token: Optional[str] = None) -> Any: 385 url = f"{self.private}/orders/{order_id}" 386 if token: 387 url += f"?token={token}" 388 return _request(url) 389 390 def refund(self, order_id: str, amount: str, reason: str = "simulator refund") -> Any: 391 return _request(f"{self.private}/orders/{order_id}/refund", "POST", 392 {"refund": amount, "reason": reason}) 393 394 def delete_order(self, order_id: str) -> Any: 395 return _request(f"{self.private}/orders/{order_id}", "DELETE") 396 397 398 CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ" 399 400 401 def encode_crock(data: bytes) -> str: 402 """The base32 Taler uses for hashes and keys (GNUNET_STRINGS_data_to_string). 403 404 Crockford's alphabet, big-endian bit order, no padding. Verified against 405 the exchange's own signing keys: the hex in `exchange.exchange_sign_keys` 406 encodes to exactly the strings /keys publishes. 407 """ 408 out = [] 409 bits = vbit = rpos = 0 410 while rpos < len(data) or vbit > 0: 411 if rpos < len(data) and vbit < 5: 412 bits = (bits << 8) | data[rpos] 413 rpos += 1 414 vbit += 8 415 if vbit < 5: 416 bits <<= (5 - vbit) 417 vbit = 5 418 out.append(CROCKFORD[(bits >> (vbit - 5)) & 31]) 419 vbit -= 5 420 return "".join(out) 421 422 423 def revoke_denomination(denom_pub_hash: bytes | str, 424 conf: str = "sim.conf", 425 run_dir: str = "/opt/taler-sim/run/stack") -> str: 426 """Revoke a denomination key, as an exchange operator would. 427 428 Destructive and stack-wide: the denomination stays revoked until the stack 429 is started again, and every wallet holding one of its coins has to recoup. 430 """ 431 import subprocess 432 crock = (denom_pub_hash if isinstance(denom_pub_hash, str) 433 else encode_crock(denom_pub_hash)) 434 proc = subprocess.run( 435 ["taler-exchange-offline", "-c", conf, 436 "revoke-denomination", crock, "upload"], 437 cwd=run_dir, capture_output=True, text=True, timeout=120, 438 ) 439 if proc.returncode != 0: 440 raise RuntimeError(f"revoking {crock} failed: " 441 f"{(proc.stderr or proc.stdout).strip()[:300]}") 442 return crock 443 444 445 def provision(env: Optional[Env] = None, 446 # Seven, not five: the harness has AVDs for workers 0..6 and 447 # worker 6 (the version matrix) banks as wallet7. A plain 448 # `python3 stack.py` used to leave that account out, and every 449 # scenario on that worker then died with 450 # `HTTP 401 ... accounts/wallet7 ... Unknown account` -- which 451 # looked exactly like a platform failure in the matrix. 452 workers: int = int(os.environ.get("SIM_WORKERS", "7"))) -> dict: 453 """Make the stack usable by a wallet: one merchant instance with a bank 454 account, and one bank customer per parallel worker.""" 455 env = env or Env.load() 456 bank, merchant = Bank(env.bank), Merchant(env.merchant) 457 out: dict[str, Any] = {"currency": env.currency} 458 # A stack start wipes the exchange database, so its master key is new while 459 # the peer wallets still remember the old one and refuse to talk to it 460 # ("the exchange changed its master public key", code 7066). Provisioning 461 # runs right after every stack start, which is exactly when they should be 462 # thrown away. 463 out["cli_wallets_removed"] = sorted( 464 p.name for p in Path("/opt/taler-sim/run").glob("cli-wallet-*.sqlite3*") 465 ) 466 for stale in Path("/opt/taler-sim/run").glob("cli-wallet-*.sqlite3*"): 467 stale.unlink(missing_ok=True) 468 accounts = [("merchant", "merchantpass1", "Simulator Shop")] 469 accounts += [(f"wallet{i + 1}", f"walletpass{i + 1}", f"Wallet {i + 1}") 470 for i in range(workers)] 471 # One more per worker for the taler-wallet-cli peer wallet. 472 accounts += [(f"peer{i + 1}", f"peerpass{i + 1}", f"Peer {i + 1}") 473 for i in range(workers)] 474 for user, password, name in accounts: 475 try: 476 bank.register(user, password, name) 477 out[f"{user}_registered"] = True 478 except HttpError as e: 479 # 409 means the account survived from an earlier run. 480 if e.status != 409: 481 raise 482 out[f"{user}_registered"] = False 483 # Keep every account well above what one round can spend: ~75 scenarios 484 # share these accounts, and a fresh one holds only the EUR:100 485 # registration bonus. 486 for user, password, _ in accounts[1:]: 487 try: 488 balance = bank.balance(user, password) 489 value = float(balance.split(":")[1]) 490 if value < 1000: 491 bank.top_up(user, "EUR:2000") 492 out[f"{user}_topped_up"] = True 493 except (HttpError, ValueError, IndexError) as e: 494 out[f"{user}_top_up_error"] = str(e)[:120] 495 merchant.create_instance() 496 merchant.add_account(bank.payto("merchant", "merchantpass1")) 497 out["merchant_instance"] = merchant.instance 498 out["balances"] = { 499 f"wallet{i + 1}": bank.balance(f"wallet{i + 1}", f"walletpass{i + 1}") 500 for i in range(workers) 501 } 502 return out 503 504 505 if __name__ == "__main__": 506 import sys 507 e = Env.load(sys.argv[1] if len(sys.argv) > 1 else DEFAULT_ENV) 508 print(json.dumps(provision(e), indent=2))