B1: plm_engine takes the modules without a database (ADR-59)
HD derivation (pure part), PSBT builder, Electrum client/merkle/quorum/scripthash, network profile, addresses and header checks move to plm_engine; the old stack imports them from there. A test forbids framework imports in the package. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
c9784efa07
commit
3ee60a23da
87 files changed
+290
-260
No files matched your search
@@ -17,9 +17,9 @@ from app.db.session import get_session
|
||||
from app.rounds.config import get_round_config
|
||||
from app.rounds.pause import pause_by_operator
|
||||
from app.rounds.service import get_active_round, payout_config_problem
|
||||
from app.wallet.address import is_valid_plm_address
|
||||
from plm_engine.address import is_valid_plm_address
|
||||
from app.wallet.hd import derive_user_wif
|
||||
from app.wallet.psbt_builder import MAX_FEE_RATE_SAT_VB
|
||||
from plm_engine.psbt_builder import MAX_FEE_RATE_SAT_VB
|
||||
|
||||
router = APIRouter(prefix="/admin", tags=["admin"])
|
||||
|
||||
|
||||
@@ -23,7 +23,7 @@ from fastapi.concurrency import run_in_threadpool
|
||||
from fastapi.responses import Response
|
||||
|
||||
from app.api.errors import http_error
|
||||
from app.wallet.address import is_valid_plm_address
|
||||
from plm_engine.address import is_valid_plm_address
|
||||
|
||||
router = APIRouter(tags=["qr"])
|
||||
|
||||
|
||||
+2
-2
@@ -10,7 +10,7 @@ from app.api.errors import ApiError
|
||||
from app.audit.log import write_audit_log
|
||||
from app.db.base import begin_immediate
|
||||
from app.db.models import PendingTransaction, Round, RoundParticipant, User, UtxoEvent
|
||||
from app.electrum.client import ElectrumClient
|
||||
from plm_engine.electrum.client import ElectrumClient
|
||||
from app.rounds.config import get_round_config
|
||||
from app.rounds.events import broadcaster
|
||||
from app.rounds.service import open_new_round_if_needed, round_accepts_bets
|
||||
@@ -18,7 +18,7 @@ from app.tx.versions import delete_versions, record_version
|
||||
from app.tx.outcome import BroadcastOutcome, TransactionNetwork, broadcast_with_verdict
|
||||
from app.wallet.balance import compute_pending_balance, recompute_balance
|
||||
from app.wallet.hd import derive_user_key
|
||||
from app.wallet.psbt_builder import (
|
||||
from plm_engine.psbt_builder import (
|
||||
MAX_PARTICIPANTS_PER_ROUND,
|
||||
RECIPIENT_VOUT,
|
||||
BuiltTransaction,
|
||||
|
||||
@@ -23,7 +23,7 @@ from sqlalchemy.ext.asyncio import async_sessionmaker
|
||||
|
||||
from app.db.models import User
|
||||
from app.electrum.listener import ElectrumListener
|
||||
from app.electrum.scripthash import address_to_scripthash
|
||||
from plm_engine.electrum.scripthash import address_to_scripthash
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
@@ -10,7 +10,7 @@ from app.db.base import begin_immediate
|
||||
from app.db.models import PendingTransaction, PendingTransactionTxid, RoundConfig, UtxoEvent
|
||||
from app.rounds.events import broadcaster
|
||||
from app.wallet.balance import recompute_balance
|
||||
from app.wallet.psbt_builder import DUST_LIMIT_SATS
|
||||
from plm_engine.psbt_builder import DUST_LIMIT_SATS
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
@@ -1,402 +0,0 @@
|
||||
import asyncio
|
||||
import hashlib
|
||||
import itertools
|
||||
import json
|
||||
import logging
|
||||
import re
|
||||
import ssl
|
||||
from typing import NamedTuple
|
||||
|
||||
from app.wallet.plm_network import GENESIS_HASH
|
||||
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
class ElectrumEndpoint(NamedTuple):
|
||||
"""One server to connect to. The listener rotates over a list of these so a
|
||||
single unreachable or misbehaving server doesn't take the platform down —
|
||||
every consumer of PLM chain data goes through this one connection.
|
||||
|
||||
`pin` (B-84, ELC-03) is the SHA-256 of the server's DER certificate, in lower-case
|
||||
hex; when set, a connection presenting any other certificate fails like an
|
||||
unreachable server. Only meaningful with TLS."""
|
||||
|
||||
host: str
|
||||
port: int
|
||||
use_ssl: bool = True
|
||||
pin: str | None = None
|
||||
|
||||
def __str__(self) -> str:
|
||||
return f"{self.host}:{self.port}{'' if self.use_ssl else ' (plaintext)'}{' (pinned)' if self.pin else ''}"
|
||||
|
||||
|
||||
_PIN_PATTERN = re.compile(r"[0-9a-f]{64}")
|
||||
|
||||
|
||||
def normalize_pin(raw: str, entry: str) -> str:
|
||||
"""A certificate pin as lower-case hex, or ValueError: 64 hexadecimal digits."""
|
||||
pin = raw.strip().lower()
|
||||
if not _PIN_PATTERN.fullmatch(pin):
|
||||
raise ValueError(f"invalid certificate pin in Electrum server {entry!r}: expected 64 hex digits (sha256)")
|
||||
return pin
|
||||
|
||||
|
||||
def parse_endpoints(
|
||||
primary_host: str,
|
||||
primary_port: int,
|
||||
primary_use_ssl: bool,
|
||||
fallback_spec: str,
|
||||
primary_pin: str = "",
|
||||
) -> list[ElectrumEndpoint]:
|
||||
"""Build the connection rotation: the primary server first, then whatever
|
||||
ELECTRUM_FALLBACK_SERVERS lists.
|
||||
|
||||
`fallback_spec` is comma-separated, each entry `host:port` (TLS, the normal
|
||||
case), `host:port:notls`, `host:port:pin=<sha256>` (TLS with a pinned certificate,
|
||||
B-84) or `host:port:notls`/`ssl`/`tls` followed by `:pin=<sha256>`. A pin on a
|
||||
plaintext entry is refused: there is no certificate to pin. `primary_pin` is the
|
||||
same pin for the primary (ELECTRUM_CERT_PIN). Malformed entries raise ValueError
|
||||
rather than being skipped: a typo in a fallback server is something to fix at
|
||||
startup, not to discover during an outage, when the fallback is what's needed.
|
||||
Duplicates are dropped, keeping first position.
|
||||
"""
|
||||
syntax = "expected host:port[:notls][:pin=<sha256>]"
|
||||
pin = normalize_pin(primary_pin, "ELECTRUM_CERT_PIN") if primary_pin.strip() else None
|
||||
if pin and not primary_use_ssl:
|
||||
raise ValueError("ELECTRUM_CERT_PIN needs TLS: ELECTRUM_USE_SSL is off")
|
||||
endpoints = [ElectrumEndpoint(primary_host, primary_port, primary_use_ssl, pin)]
|
||||
for raw in fallback_spec.split(","):
|
||||
entry = raw.strip()
|
||||
if not entry:
|
||||
continue
|
||||
parts = entry.split(":")
|
||||
if not 2 <= len(parts) <= 4:
|
||||
raise ValueError(f"invalid Electrum server {entry!r}: {syntax}")
|
||||
host, port = parts[0].strip(), parts[1].strip()
|
||||
if not host or not port.isdigit():
|
||||
raise ValueError(f"invalid Electrum server {entry!r}: {syntax}")
|
||||
use_ssl = True
|
||||
pin = None
|
||||
mode_seen = False
|
||||
for extra in parts[2:]:
|
||||
extra = extra.strip()
|
||||
if extra.lower().startswith("pin="):
|
||||
if pin is not None:
|
||||
raise ValueError(f"invalid Electrum server {entry!r}: more than one pin")
|
||||
pin = normalize_pin(extra[4:], entry)
|
||||
continue
|
||||
flag = extra.lower()
|
||||
if mode_seen or flag not in ("ssl", "tls", "notls", "plain"):
|
||||
raise ValueError(f"invalid TLS flag {flag!r} in Electrum server {entry!r}")
|
||||
mode_seen = True
|
||||
use_ssl = flag in ("ssl", "tls")
|
||||
if pin and not use_ssl:
|
||||
raise ValueError(f"invalid Electrum server {entry!r}: a pin needs TLS")
|
||||
endpoints.append(ElectrumEndpoint(host, int(port), use_ssl, pin))
|
||||
|
||||
deduped: list[ElectrumEndpoint] = []
|
||||
seen: set[tuple] = set()
|
||||
for endpoint in endpoints:
|
||||
key = (endpoint.host, endpoint.port, endpoint.use_ssl)
|
||||
if key not in seen:
|
||||
seen.add(key)
|
||||
deduped.append(endpoint)
|
||||
return deduped
|
||||
|
||||
|
||||
|
||||
# Every request is bounded: without this, a half-open socket (the peer vanished
|
||||
# without a FIN, or the read loop died — see _read_loop) leaves `await future`
|
||||
# hanging forever, and with it whatever was awaiting the call. That used to be
|
||||
# unbounded, which meant a POST /bets could hang while holding the per-user lock
|
||||
# and the confirmation poller could stop polling permanently.
|
||||
_REQUEST_TIMEOUT_SECONDS = 15
|
||||
|
||||
# Longest reply line the client accepts (B-75, ELC-20). asyncio's default StreamReader
|
||||
# limit is 64 KiB, and a longer line used to raise out of the read loop and close the
|
||||
# only connection: the pool address's get_history passed that after ~800 transactions
|
||||
# (and a few hundred dust outputs sent to any public address do it on purpose), after
|
||||
# which every confirmation poll dropped the connection and payouts never confirmed.
|
||||
_MAX_LINE_BYTES = 16 * 1024 * 1024
|
||||
_READ_CHUNK_BYTES = 64 * 1024
|
||||
# How much of each end of a discarded line is kept to find the reply's `id` in, so the
|
||||
# request it answered can fail at once instead of waiting out the 15s timeout.
|
||||
_ID_SNIFF_BYTES = 256
|
||||
_ID_PATTERN = re.compile(rb'"id"\s*:\s*(\d+)')
|
||||
|
||||
|
||||
class ElectrumError(Exception):
|
||||
pass
|
||||
|
||||
|
||||
class ElectrumRpcError(ElectrumError):
|
||||
"""The server *answered* with a JSON-RPC `error` object (B-76, TX-04). It is the
|
||||
only failure that says anything about the request itself: a timeout, a dropped
|
||||
connection or a write error (plain ElectrumError) leaves it unknown whether the
|
||||
server ever acted on it. `args[0]` is the error object as the server sent it."""
|
||||
|
||||
@property
|
||||
def message(self) -> str:
|
||||
detail = self.args[0] if self.args else ""
|
||||
if isinstance(detail, dict):
|
||||
return str(detail.get("message", detail))
|
||||
return str(detail)
|
||||
|
||||
|
||||
class ElectrumClient:
|
||||
"""Minimal asyncio Electrum protocol client: line-delimited JSON-RPC over TLS.
|
||||
|
||||
Push notifications (blockchain.headers.subscribe, blockchain.scripthash.subscribe)
|
||||
arrive under the *same* method name as the subscribe call, multiplexed for every
|
||||
scripthash subscribed — callers read `notifications(method)` and, for scripthash
|
||||
pushes, dispatch on `params[0]` (the scripthash) themselves.
|
||||
|
||||
A dead connection is observable rather than silent: `wait_closed()` resolves as
|
||||
soon as the read loop terminates for any reason, which is what lets
|
||||
ElectrumListener notice the drop and reconnect instead of waiting forever on
|
||||
notification queues nobody will ever fill again.
|
||||
"""
|
||||
|
||||
def __init__(self, host: str, port: int, use_ssl: bool = True, pin: str | None = None):
|
||||
self.host = host
|
||||
self.port = port
|
||||
self.use_ssl = use_ssl
|
||||
self.pin = pin.lower() if pin else None
|
||||
self._reader: asyncio.StreamReader | None = None
|
||||
self._writer: asyncio.StreamWriter | None = None
|
||||
self._id_counter = itertools.count(1)
|
||||
self._pending: dict[int, asyncio.Future] = {}
|
||||
self._subscriptions: dict[str, asyncio.Queue] = {}
|
||||
self._read_task: asyncio.Task | None = None
|
||||
self._closed = asyncio.Event()
|
||||
|
||||
async def connect(self) -> None:
|
||||
# Electrum servers commonly present self-signed certs; the protocol's trust
|
||||
# model is server consensus, not TLS PKI, so we only use SSL for transport
|
||||
# encryption and don't verify the certificate chain/hostname. What can be
|
||||
# asked instead is that the certificate be *the* one the operator pinned
|
||||
# (B-84, ELC-03): without a pin, whoever sits on the path to a server takes
|
||||
# its place, and only the quorum stands between that and the draw.
|
||||
ssl_context = None
|
||||
if self.use_ssl:
|
||||
ssl_context = ssl.create_default_context()
|
||||
ssl_context.check_hostname = False
|
||||
ssl_context.verify_mode = ssl.CERT_NONE
|
||||
self._reader, self._writer = await asyncio.open_connection(
|
||||
self.host, self.port, ssl=ssl_context, limit=_MAX_LINE_BYTES
|
||||
)
|
||||
if self.pin:
|
||||
try:
|
||||
self._check_pin()
|
||||
except ElectrumError:
|
||||
self._writer.close()
|
||||
raise
|
||||
self._read_task = asyncio.create_task(self._read_loop())
|
||||
await self.request("server.version", ["plm-lottery", "1.4"])
|
||||
try:
|
||||
await self._check_genesis()
|
||||
except ElectrumError:
|
||||
self._read_task.cancel()
|
||||
self._writer.close()
|
||||
raise
|
||||
|
||||
async def _check_genesis(self) -> None:
|
||||
"""The server must be on PLM's chain, not just any chain with valid headers: PLM shares
|
||||
Bitcoin's genesis and powLimit, so only `server.features` tells them apart (B-99, ELC-30)."""
|
||||
features = await self.request("server.features")
|
||||
genesis = features.get("genesis_hash") if isinstance(features, dict) else None
|
||||
if genesis != GENESIS_HASH:
|
||||
raise ElectrumError(f"{self.host}:{self.port} is not on the PLM chain (genesis {genesis!r})")
|
||||
|
||||
def _check_pin(self) -> None:
|
||||
"""The server's DER certificate must hash to the pinned SHA-256 (B-84, ELC-03)."""
|
||||
ssl_object = self._writer.get_extra_info("ssl_object") if self._writer is not None else None
|
||||
der = ssl_object.getpeercert(binary_form=True) if ssl_object is not None else None
|
||||
if not der:
|
||||
raise ElectrumError(f"{self.host}:{self.port} presented no certificate to check against the pin")
|
||||
if hashlib.sha256(der).hexdigest() != self.pin:
|
||||
raise ElectrumError(f"{self.host}:{self.port} certificate does not match the configured pin")
|
||||
|
||||
async def close(self) -> None:
|
||||
self._closed.set()
|
||||
if self._read_task is not None:
|
||||
self._read_task.cancel()
|
||||
if self._writer is not None:
|
||||
self._writer.close()
|
||||
try:
|
||||
await asyncio.wait_for(self._writer.wait_closed(), timeout=2)
|
||||
except (ssl.SSLError, TimeoutError, asyncio.TimeoutError, ConnectionError):
|
||||
pass # some Electrum servers don't send a clean TLS close_notify
|
||||
|
||||
async def wait_closed(self) -> None:
|
||||
"""Resolves once this connection is gone — read loop finished (peer closed,
|
||||
protocol error, TLS failure) or close() was called. ElectrumListener races
|
||||
this against its notification consumers so a drop triggers a reconnect."""
|
||||
await self._closed.wait()
|
||||
|
||||
async def request(self, method: str, params: list | None = None) -> object:
|
||||
if self._writer is None or self._closed.is_set():
|
||||
raise ElectrumError("not connected")
|
||||
request_id = next(self._id_counter)
|
||||
future: asyncio.Future = asyncio.get_running_loop().create_future()
|
||||
self._pending[request_id] = future
|
||||
payload = json.dumps({"id": request_id, "method": method, "params": params or []}) + "\n"
|
||||
try:
|
||||
self._writer.write(payload.encode())
|
||||
await self._writer.drain()
|
||||
except (ConnectionError, ssl.SSLError, OSError) as exc:
|
||||
self._pending.pop(request_id, None)
|
||||
self._closed.set()
|
||||
raise ElectrumError(f"write failed: {exc}") from exc
|
||||
try:
|
||||
return await asyncio.wait_for(future, timeout=_REQUEST_TIMEOUT_SECONDS)
|
||||
except (TimeoutError, asyncio.TimeoutError) as exc:
|
||||
self._pending.pop(request_id, None)
|
||||
# A server that owes us a reply and never sends one is indistinguishable
|
||||
# from a dead socket, and retrying on the same connection would keep
|
||||
# hitting it — tear it down so the listener reconnects.
|
||||
self._closed.set()
|
||||
raise ElectrumError(f"{method} timed out after {_REQUEST_TIMEOUT_SECONDS}s") from exc
|
||||
|
||||
async def ping(self) -> None:
|
||||
"""Keepalive: Electrum servers drop idle connections (commonly after ~10
|
||||
minutes), which on a quiet instance would otherwise be the normal way this
|
||||
connection dies. Called periodically by ElectrumListener."""
|
||||
await self.request("server.ping")
|
||||
|
||||
def notifications(self, method: str) -> asyncio.Queue:
|
||||
return self._subscriptions.setdefault(method, asyncio.Queue())
|
||||
|
||||
async def subscribe_headers(self) -> dict:
|
||||
self.notifications("blockchain.headers.subscribe")
|
||||
return await self.request("blockchain.headers.subscribe")
|
||||
|
||||
async def subscribe_scripthash(self, scripthash: str) -> str | None:
|
||||
self.notifications("blockchain.scripthash.subscribe")
|
||||
return await self.request("blockchain.scripthash.subscribe", [scripthash])
|
||||
|
||||
async def listunspent(self, scripthash: str) -> list[dict]:
|
||||
return await self.request("blockchain.scripthash.listunspent", [scripthash])
|
||||
|
||||
async def get_history(self, scripthash: str) -> list[dict]:
|
||||
"""Every transaction touching `scripthash`, each as {"tx_hash", "height"} —
|
||||
height > 0 means confirmed at that height, height <= 0 means still in the
|
||||
mempool. Used instead of blockchain.transaction.get's verbose=True mode
|
||||
for confirmation/existence checks (B-41): several Electrum server
|
||||
implementations and versions reject the verbose flag outright ("verbose
|
||||
transactions are currently unsupported"), while get_history is a plain,
|
||||
universally-supported method every server must implement.
|
||||
"""
|
||||
return await self.request("blockchain.scripthash.get_history", [scripthash])
|
||||
|
||||
async def broadcast(self, raw_tx_hex: str) -> str:
|
||||
return await self.request("blockchain.transaction.broadcast", [raw_tx_hex])
|
||||
|
||||
async def get_transaction(self, txid: str, verbose: bool = False) -> object:
|
||||
return await self.request("blockchain.transaction.get", [txid, verbose])
|
||||
|
||||
async def get_merkle(self, txid: str, height: int) -> dict:
|
||||
"""The merkle branch proving `txid` is in the block at `height` (B-83, ELC-26)."""
|
||||
return await self.request("blockchain.transaction.get_merkle", [txid, height])
|
||||
|
||||
async def get_block_header(self, height: int) -> str:
|
||||
return await self.request("blockchain.block.header", [height])
|
||||
|
||||
async def get_block_headers(self, start_height: int, count: int) -> dict:
|
||||
"""`count` consecutive headers from `start_height` (B-74, ELC-12), as the server's
|
||||
{"count", "hex", "max"}: `hex` is the 80-byte headers concatenated, and the server
|
||||
may return fewer than asked (never more than its `max`)."""
|
||||
return await self.request("blockchain.block.headers", [start_height, count])
|
||||
|
||||
async def _read_loop(self) -> None:
|
||||
"""Frame the stream into lines by hand rather than with StreamReader.readline:
|
||||
readline raises on a line over the limit, and that exception used to end this
|
||||
loop and with it the connection. An oversized line is now dropped up to its
|
||||
newline (B-75, ELC-20) and the connection stays up."""
|
||||
assert self._reader is not None
|
||||
buffer = bytearray()
|
||||
discarding = False
|
||||
head = b""
|
||||
tail = b""
|
||||
try:
|
||||
while True:
|
||||
chunk = await self._reader.read(_READ_CHUNK_BYTES)
|
||||
if not chunk:
|
||||
break
|
||||
while chunk:
|
||||
newline = chunk.find(b"\n")
|
||||
piece = chunk if newline < 0 else chunk[:newline]
|
||||
chunk = b"" if newline < 0 else chunk[newline + 1 :]
|
||||
if discarding:
|
||||
tail = (tail + piece)[-_ID_SNIFF_BYTES:]
|
||||
else:
|
||||
buffer += piece
|
||||
if len(buffer) > _MAX_LINE_BYTES:
|
||||
discarding = True
|
||||
head = bytes(buffer[:_ID_SNIFF_BYTES])
|
||||
tail = bytes(buffer[-_ID_SNIFF_BYTES:])
|
||||
buffer.clear()
|
||||
if newline >= 0:
|
||||
if discarding:
|
||||
self._fail_unreadable_reply(head + b" " + tail, "reply exceeds the line limit")
|
||||
discarding = False
|
||||
else:
|
||||
self._handle_line(bytes(buffer))
|
||||
buffer.clear()
|
||||
if buffer and not discarding:
|
||||
self._handle_line(bytes(buffer)) # a final line the server never terminated
|
||||
finally:
|
||||
# Whatever ended this loop — clean EOF, TLS failure — the
|
||||
# connection is unusable from here on. Setting this is what makes the
|
||||
# death observable to wait_closed(), and so to the listener's reconnect
|
||||
# logic; without it the listener waited on notification queues nobody
|
||||
# would ever fill again, forever (B-01).
|
||||
self._closed.set()
|
||||
error = ElectrumError("connection closed")
|
||||
for future in self._pending.values():
|
||||
if not future.done():
|
||||
future.set_exception(error)
|
||||
self._pending.clear()
|
||||
|
||||
def _handle_line(self, line: bytes) -> None:
|
||||
if not line.strip():
|
||||
return
|
||||
try:
|
||||
message = json.loads(line)
|
||||
except ValueError:
|
||||
# A reply that is not JSON is a problem of that one request, not of the
|
||||
# connection (B-75).
|
||||
self._fail_unreadable_reply(line[:_ID_SNIFF_BYTES] + b" " + line[-_ID_SNIFF_BYTES:], "reply is not valid JSON")
|
||||
return
|
||||
if not isinstance(message, dict):
|
||||
logger.warning("ignoring an Electrum message that is not a JSON object")
|
||||
return
|
||||
self._dispatch(message)
|
||||
|
||||
def _fail_unreadable_reply(self, sample: bytes, reason: str) -> None:
|
||||
"""Fail the request an unusable reply belongs to, when its `id` can be read
|
||||
from `sample` (the first and last bytes of the line); otherwise that request
|
||||
fails by its own timeout (ELC-04)."""
|
||||
logger.warning("dropping an unusable Electrum reply: %s", reason)
|
||||
for match in _ID_PATTERN.finditer(sample):
|
||||
future = self._pending.pop(int(match.group(1)), None)
|
||||
if future is not None:
|
||||
if not future.done():
|
||||
future.set_exception(ElectrumError(reason))
|
||||
return
|
||||
|
||||
def _dispatch(self, message: dict) -> None:
|
||||
message_id = message.get("id")
|
||||
if message_id is not None and message_id in self._pending:
|
||||
future = self._pending.pop(message_id)
|
||||
if future.done():
|
||||
return
|
||||
if message.get("error"):
|
||||
future.set_exception(ElectrumRpcError(message["error"]))
|
||||
else:
|
||||
future.set_result(message.get("result"))
|
||||
elif "method" in message:
|
||||
queue = self._subscriptions.get(message["method"])
|
||||
if queue is not None:
|
||||
queue.put_nowait(message.get("params"))
|
||||
@@ -23,11 +23,11 @@ from app.deposits.service import (
|
||||
reinstate_reappeared_utxos,
|
||||
)
|
||||
from app.config import MIN_QUORUM_RESPONSES
|
||||
from app.electrum.client import ElectrumClient, ElectrumEndpoint, ElectrumRpcError
|
||||
from app.electrum.merkle import proof_matches_header
|
||||
from app.electrum.quorum import ServerAnswers
|
||||
from app.electrum.scripthash import address_to_scripthash
|
||||
from app.rounds.draw import (
|
||||
from plm_engine.electrum.client import ElectrumClient, ElectrumEndpoint, ElectrumRpcError
|
||||
from plm_engine.electrum.merkle import proof_matches_header
|
||||
from plm_engine.electrum.quorum import ServerAnswers
|
||||
from plm_engine.electrum.scripthash import address_to_scripthash
|
||||
from plm_engine.headers import (
|
||||
HeaderValidationError,
|
||||
header_hex_to_block_hash,
|
||||
header_meets_its_own_target,
|
||||
|
||||
@@ -1,57 +0,0 @@
|
||||
"""Merkle proofs (B-83, TX-22, ELC-26).
|
||||
|
||||
`blockchain.transaction.get_merkle` answers with the branch that links a transaction to
|
||||
its block's merkle root. Checking it against a header **we hold** is what turns "a server
|
||||
says this tx is at height h" into something a hostile server cannot fake without mining.
|
||||
"""
|
||||
|
||||
import hashlib
|
||||
|
||||
_HEADER_LENGTH_BYTES = 80
|
||||
_MERKLE_ROOT_OFFSET = 36
|
||||
_MERKLE_ROOT_LENGTH = 32
|
||||
_MAX_BRANCH_LENGTH = 40 # 2^40 transactions in a block is already absurd
|
||||
|
||||
|
||||
def _sha256d(data: bytes) -> bytes:
|
||||
return hashlib.sha256(hashlib.sha256(data).digest()).digest()
|
||||
|
||||
|
||||
def header_merkle_root(header_hex: str) -> bytes:
|
||||
"""The merkle root committed to by a raw 80-byte header, in internal byte order."""
|
||||
header = bytes.fromhex(header_hex)
|
||||
if len(header) != _HEADER_LENGTH_BYTES:
|
||||
raise ValueError(f"a block header is {_HEADER_LENGTH_BYTES} bytes, got {len(header)}")
|
||||
return header[_MERKLE_ROOT_OFFSET : _MERKLE_ROOT_OFFSET + _MERKLE_ROOT_LENGTH]
|
||||
|
||||
|
||||
def merkle_root_from_branch(txid: str, branch: list[str], position: int) -> bytes:
|
||||
"""The merkle root (internal byte order) a transaction `txid` at index `position` of
|
||||
its block reaches through `branch` — the sibling hashes, bottom-up, in the display
|
||||
order Electrum uses for txids."""
|
||||
if position < 0 or len(branch) > _MAX_BRANCH_LENGTH or position >> len(branch):
|
||||
raise ValueError("merkle position does not fit the branch")
|
||||
current = bytes.fromhex(txid)[::-1]
|
||||
index = position
|
||||
for sibling_hex in branch:
|
||||
sibling = bytes.fromhex(sibling_hex)[::-1]
|
||||
if len(sibling) != 32:
|
||||
raise ValueError("merkle branch element is not 32 bytes")
|
||||
current = _sha256d(sibling + current) if index & 1 else _sha256d(current + sibling)
|
||||
index >>= 1
|
||||
return current
|
||||
|
||||
|
||||
def proof_matches_header(txid: str, height: int, proof: object, header_hex: str) -> bool:
|
||||
"""Does `proof` — a `get_merkle` reply — put `txid` in the block at `height` whose
|
||||
header is `header_hex`? Any malformed reply is simply "no"."""
|
||||
try:
|
||||
if not isinstance(proof, dict) or int(proof["block_height"]) != height:
|
||||
return False
|
||||
branch = proof["merkle"]
|
||||
if not isinstance(branch, list):
|
||||
return False
|
||||
root = merkle_root_from_branch(txid, [str(item) for item in branch], int(proof["pos"]))
|
||||
return root == header_merkle_root(header_hex)
|
||||
except (KeyError, TypeError, ValueError):
|
||||
return False
|
||||
@@ -1,27 +0,0 @@
|
||||
"""What a question put to every server came back with (B-78).
|
||||
|
||||
`active` is the answer of the connection the platform is running on, `others` those of
|
||||
each other configured server in configuration order; `None` stands for "no usable
|
||||
answer" (unreachable, timed out, an error that is not an answer)."""
|
||||
|
||||
from typing import NamedTuple
|
||||
|
||||
|
||||
class ServerAnswers(NamedTuple):
|
||||
active: object | None
|
||||
others: tuple
|
||||
others_needed: int # how many of `others` must have answered for the network to count
|
||||
|
||||
@property
|
||||
def answered_others(self) -> list:
|
||||
return [answer for answer in self.others if answer is not None]
|
||||
|
||||
@property
|
||||
def complete(self) -> bool:
|
||||
"""Enough of the network answered for its silence to mean something: the active
|
||||
server and at least `others_needed` of the others."""
|
||||
return self.active is not None and len(self.answered_others) >= self.others_needed
|
||||
|
||||
@property
|
||||
def all(self) -> list:
|
||||
return ([] if self.active is None else [self.active]) + self.answered_others
|
||||
@@ -1,15 +0,0 @@
|
||||
import hashlib
|
||||
|
||||
from embit.script import Script
|
||||
|
||||
|
||||
def address_to_scripthash(address: str) -> str:
|
||||
"""Electrum protocol scripthash: sha256(scriptPubKey), byte-reversed, hex.
|
||||
|
||||
Uses `.data` (the raw scriptPubKey bytes), not `.serialize()` — the latter
|
||||
prefixes a compact-size length byte meant for embedding the script as pushdata
|
||||
elsewhere (e.g. a P2SH redeemScript), which is not part of the actual on-chain
|
||||
output script and produces a wrong (unmatchable) scripthash if used here.
|
||||
"""
|
||||
script_pubkey = Script.from_address(address).data
|
||||
return hashlib.sha256(script_pubkey).digest()[::-1].hex()
|
||||
+1
-1
@@ -27,7 +27,7 @@ from app.api.errors import ApiError
|
||||
from app.config import settings, validate_quorum_servers, validate_runtime_secrets
|
||||
from app.db.base import AsyncSessionLocal
|
||||
from app.deposits.reconcile import DepositReconciler
|
||||
from app.electrum.client import ElectrumClient, ElectrumEndpoint, parse_endpoints
|
||||
from plm_engine.electrum.client import ElectrumClient, ElectrumEndpoint, parse_endpoints
|
||||
from app.electrum.listener import ElectrumListener
|
||||
from app.rounds.scheduler import RoundScheduler
|
||||
from app.rounds.pause import pause_by_operator
|
||||
|
||||
@@ -1,101 +0,0 @@
|
||||
import hashlib
|
||||
|
||||
# Byte offsets of a standard 80-byte block header: version(4) + prev_block(32) +
|
||||
# merkle_root(32) + timestamp(4) + bits(4) + nonce(4).
|
||||
_HEADER_LENGTH_BYTES = 80
|
||||
_PREV_BLOCK_OFFSET = 4
|
||||
_PREV_BLOCK_LENGTH = 32
|
||||
_BITS_OFFSET = 72
|
||||
_BITS_LENGTH = 4
|
||||
|
||||
|
||||
# B-74 (ELC-11): the proof-of-work floor of PLM mainnet — `consensus.powLimit` in
|
||||
# palladiumcore/src/chainparams.cpp, the same as Bitcoin's. A header claiming a target
|
||||
# *easier* than this was not mined to the chain's rules, whatever its own hash says, so
|
||||
# the claimed target alone (which is whoever fabricates the header's to choose) is not a
|
||||
# proof of work. Read through the module at call time so a test can swap in a regtest
|
||||
# limit to mine headers cheaply; production code never changes it.
|
||||
MAINNET_POW_LIMIT = int("00000000" + "ff" * 28, 16)
|
||||
POW_LIMIT = MAINNET_POW_LIMIT
|
||||
|
||||
|
||||
class HeaderValidationError(Exception):
|
||||
"""Raised by ElectrumListener._apply_header (B-28) when a header either doesn't
|
||||
satisfy the difficulty target it claims for itself, or doesn't chain from the
|
||||
previously accepted tip. Letting this propagate out of the header-consuming
|
||||
task ends the current Electrum session the same way a dropped connection would
|
||||
(see ElectrumListener._run_once), so the listener rotates to the next
|
||||
configured server instead of trusting a header a server just forged."""
|
||||
|
||||
|
||||
def header_hex_to_block_hash(header_hex: str) -> str:
|
||||
"""Block hash from a raw Electrum header: sha256d, byte-reversed, hex.
|
||||
Verified against a real mainnet block (blockchain.transaction.get's own
|
||||
reported blockhash) during development."""
|
||||
header_bytes = bytes.fromhex(header_hex)
|
||||
digest = hashlib.sha256(hashlib.sha256(header_bytes).digest()).digest()
|
||||
return digest[::-1].hex()
|
||||
|
||||
|
||||
def header_prev_hash(header_hex: str) -> str:
|
||||
"""The header's `prev_block` field, byte-reversed to the same conventional
|
||||
(display) order as header_hex_to_block_hash's return value, so the two can be
|
||||
compared directly to check that one header actually chains from another."""
|
||||
header_bytes = bytes.fromhex(header_hex)
|
||||
prev = header_bytes[_PREV_BLOCK_OFFSET : _PREV_BLOCK_OFFSET + _PREV_BLOCK_LENGTH]
|
||||
return prev[::-1].hex()
|
||||
|
||||
|
||||
def _target_from_bits(bits: int) -> int:
|
||||
"""Decompress Bitcoin-style compact `nBits` difficulty encoding into the full
|
||||
256-bit target a valid header's hash must be less than or equal to."""
|
||||
exponent = bits >> 24
|
||||
mantissa = bits & 0xFFFFFF
|
||||
if exponent <= 3:
|
||||
return mantissa >> (8 * (3 - exponent))
|
||||
return mantissa << (8 * (exponent - 3))
|
||||
|
||||
|
||||
def header_meets_its_own_target(header_hex: str) -> bool:
|
||||
"""Whether this header's hash satisfies the difficulty target *it claims for
|
||||
itself* (the `bits` field), and that target is no easier than the chain's powLimit
|
||||
(B-74, ELC-11 — without that, a fabricated header just claims `bits = 0x207fffff`). Rejects a header that was never actually mined —
|
||||
e.g. one fabricated wholesale by a hostile or MITM'd Electrum server (B-28),
|
||||
since satisfying a self-chosen target still requires real proof-of-work.
|
||||
|
||||
This does NOT — and, short of downloading and validating the full header
|
||||
chain's difficulty-retarget history, cannot — catch a header honestly mined at
|
||||
a real but implausibly low self-chosen difficulty: a server could still declare
|
||||
an easy target and grind it out with modest hardware. That residual risk is why
|
||||
the draw additionally requires the winning block's header to be corroborated by
|
||||
the configured servers at a fixed height before using it as the seed (see
|
||||
ElectrumListener.agreed_block_hash and rounds/scheduler.py:_wait_for_draw_block)
|
||||
rather than relying on this check alone.
|
||||
"""
|
||||
header_bytes = bytes.fromhex(header_hex)
|
||||
if len(header_bytes) != _HEADER_LENGTH_BYTES:
|
||||
return False
|
||||
bits = int.from_bytes(header_bytes[_BITS_OFFSET : _BITS_OFFSET + _BITS_LENGTH], "little")
|
||||
target = _target_from_bits(bits)
|
||||
if target <= 0 or target > POW_LIMIT: # B-74: not easier than the chain's powLimit
|
||||
return False
|
||||
digest = hashlib.sha256(hashlib.sha256(header_bytes).digest()).digest()
|
||||
# The hash as the integer comparable against `target`: this is the same digest
|
||||
# header_hex_to_block_hash reverses into the conventional display hex, so
|
||||
# reading it byte-reversed as a big-endian int is equivalent to reading the
|
||||
# original digest bytes as little-endian — both give the same integer.
|
||||
hash_int = int.from_bytes(digest, "little")
|
||||
return hash_int <= target
|
||||
|
||||
|
||||
# The draw primitives live in `plm_engine.draw` (shared with the Django site); re-exported here so the
|
||||
# old modules and their tests keep working until the old backend is removed (roadmap D1).
|
||||
from plm_engine.draw import ( # noqa: E402,F401
|
||||
draw_index,
|
||||
draw_seed,
|
||||
draw_winner,
|
||||
new_server_seed,
|
||||
participants_hash,
|
||||
server_seed_commitment,
|
||||
sha256_hex,
|
||||
)
|
||||
@@ -13,9 +13,9 @@ from app.audit.log import write_audit_log
|
||||
from app.db.base import begin_immediate
|
||||
from app.db.models import AuditLog, PendingTransaction, Round, RoundParticipant, User
|
||||
from app.electrum.listener import ElectrumListener
|
||||
from app.electrum.scripthash import address_to_scripthash
|
||||
from plm_engine.electrum.scripthash import address_to_scripthash
|
||||
from app.rounds.config import get_round_config
|
||||
from app.rounds.draw import (
|
||||
from plm_engine.draw import (
|
||||
draw_index,
|
||||
draw_seed,
|
||||
new_server_seed,
|
||||
@@ -29,8 +29,8 @@ from app.tx.outcome import BroadcastOutcome, broadcast_with_verdict
|
||||
from app.tx.versions import record_version
|
||||
from app.wallet.hd import derive_pool_address, derive_round_pool_key
|
||||
from app.wallet.keystore import decrypt_round_seed, encrypt_round_seed
|
||||
from app.wallet.plm_network import PLM_MAINNET
|
||||
from app.wallet.psbt_builder import InsufficientFundsError, Utxo, build_payout_transaction
|
||||
from plm_engine.network import PLM_MAINNET
|
||||
from plm_engine.psbt_builder import InsufficientFundsError, Utxo, build_payout_transaction
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
@@ -8,10 +8,10 @@ from sqlalchemy.ext.asyncio import AsyncSession
|
||||
from app.db.models import Round, RoundConfig
|
||||
from app.rounds.config import get_round_config
|
||||
from app.rounds.events import broadcaster
|
||||
from app.rounds.draw import new_server_seed, server_seed_commitment
|
||||
from plm_engine.draw import new_server_seed, server_seed_commitment
|
||||
from app.wallet.hd import derive_pool_address
|
||||
from app.wallet.keystore import encrypt_round_seed
|
||||
from app.wallet.psbt_builder import (
|
||||
from plm_engine.psbt_builder import (
|
||||
DUST_LIMIT_SATS,
|
||||
MAX_PARTICIPANTS_PER_ROUND,
|
||||
MAX_TX_INPUTS,
|
||||
|
||||
+3
-3
@@ -22,13 +22,13 @@ from app.db.models import (
|
||||
UtxoEvent,
|
||||
Withdrawal,
|
||||
)
|
||||
from app.electrum.client import ElectrumClient
|
||||
from plm_engine.electrum.client import ElectrumClient
|
||||
from app.rounds.config import get_round_config
|
||||
from app.tx.outcome import BroadcastOutcome, TransactionNetwork, broadcast_with_verdict
|
||||
from app.tx.versions import record_version
|
||||
from app.wallet.hd import derive_pool_address, derive_round_pool_key, derive_user_key
|
||||
from app.wallet.plm_network import PLM_MAINNET
|
||||
from app.wallet.psbt_builder import DUST_LIMIT_SATS, MAX_FEE_RATE_SAT_VB, RBF_SEQUENCE, estimate_vsize
|
||||
from plm_engine.network import PLM_MAINNET
|
||||
from plm_engine.psbt_builder import DUST_LIMIT_SATS, MAX_FEE_RATE_SAT_VB, RBF_SEQUENCE, estimate_vsize
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
@@ -8,8 +8,8 @@ from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
|
||||
|
||||
from app.db.base import begin_immediate
|
||||
from app.db.models import PendingTransaction
|
||||
from app.electrum.client import ElectrumClient
|
||||
from app.electrum.scripthash import address_to_scripthash
|
||||
from plm_engine.electrum.client import ElectrumClient
|
||||
from plm_engine.electrum.scripthash import address_to_scripthash
|
||||
from app.rounds.events import broadcaster
|
||||
from app.tx.broadcast import adopt_version
|
||||
from app.tx.pending_address import own_address_for
|
||||
|
||||
+1
-1
@@ -19,7 +19,7 @@ import logging
|
||||
from enum import Enum
|
||||
from typing import NamedTuple, Protocol
|
||||
|
||||
from app.electrum.client import ElectrumRpcError
|
||||
from plm_engine.electrum.client import ElectrumRpcError
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
+3
-3
@@ -54,9 +54,9 @@ from app.db.models import (
|
||||
UtxoEvent,
|
||||
Withdrawal,
|
||||
)
|
||||
from app.electrum.client import ElectrumClient
|
||||
from app.electrum.quorum import ServerAnswers
|
||||
from app.electrum.scripthash import address_to_scripthash
|
||||
from plm_engine.electrum.client import ElectrumClient
|
||||
from plm_engine.electrum.quorum import ServerAnswers
|
||||
from plm_engine.electrum.scripthash import address_to_scripthash
|
||||
from app.rounds.events import broadcaster
|
||||
from app.rounds.pause import pause_automatically
|
||||
from app.tx.broadcast import adopt_version
|
||||
|
||||
@@ -1,27 +0,0 @@
|
||||
"""Validation for PLM addresses supplied by the user (withdrawal destinations).
|
||||
|
||||
embit's `Script.from_address` accepts a well-formed bech32 address from *any*
|
||||
chain — a Bitcoin `bc1...` parses fine and yields a perfectly valid witness
|
||||
program — so parse-success alone is not a sufficient check here: a withdrawal
|
||||
to a `bc1...` address would build, sign and broadcast normally on PLM and land
|
||||
on a script nobody holds the key for. The HRP check below is what makes the
|
||||
destination actually PLM, and it matches what the withdrawal form already
|
||||
tells the user (bech32 `plm1q...` only).
|
||||
"""
|
||||
|
||||
from embit import script
|
||||
from embit.base import EmbitError
|
||||
|
||||
from app.wallet.plm_network import PLM_MAINNET
|
||||
|
||||
_BECH32_PREFIX = PLM_MAINNET["bech32"] + "1"
|
||||
|
||||
|
||||
def is_valid_plm_address(address: str) -> bool:
|
||||
if not address.startswith(_BECH32_PREFIX):
|
||||
return False
|
||||
try:
|
||||
script.Script.from_address(address)
|
||||
except EmbitError:
|
||||
return False
|
||||
return True
|
||||
@@ -3,7 +3,7 @@ from sqlalchemy import func, select
|
||||
from sqlalchemy.ext.asyncio import AsyncSession
|
||||
|
||||
from app.db.models import PendingTransaction, User, UtxoEvent
|
||||
from app.wallet.plm_network import PLM_MAINNET
|
||||
from plm_engine.network import PLM_MAINNET
|
||||
|
||||
|
||||
async def recompute_balance(session: AsyncSession, user_id: int) -> int:
|
||||
|
||||
+13
-39
@@ -1,12 +1,11 @@
|
||||
import os
|
||||
|
||||
from embit import script
|
||||
from embit.bip32 import HDKey
|
||||
from embit.ec import PrivateKey
|
||||
|
||||
from app.config import settings
|
||||
from plm_engine import hd as engine
|
||||
from app.wallet.keystore import decrypt_xprv, encrypt_xprv, write_secret_file
|
||||
from app.wallet.plm_network import ACCOUNT_PATH, PLM_MAINNET
|
||||
from plm_engine.network import ACCOUNT_PATH, PLM_MAINNET
|
||||
|
||||
_account_key: HDKey | None = None
|
||||
|
||||
@@ -31,55 +30,30 @@ def _load_account_key() -> HDKey:
|
||||
|
||||
|
||||
def derive_user_key(derivation_index: int) -> HDKey:
|
||||
return _load_account_key().derive(f"0/{derivation_index}")
|
||||
return engine.user_key(_load_account_key(), derivation_index)
|
||||
|
||||
|
||||
def derive_user_address(derivation_index: int) -> str:
|
||||
pub = derive_user_key(derivation_index).to_public()
|
||||
return script.p2wpkh(pub).address(network=PLM_MAINNET)
|
||||
return engine.user_address(_load_account_key(), derivation_index)
|
||||
|
||||
|
||||
def derive_user_wif(derivation_index: int) -> str:
|
||||
"""Exports a user's raw private key (WIF) for manual server-side intervention
|
||||
(e.g. sweeping funds back to a user, or out, if something gets stuck). This is
|
||||
a custodial system — the server already holds the master key this is derived
|
||||
from — but callers must still treat the result as a live secret: log access,
|
||||
never persist it, never return it over an unauthenticated channel."""
|
||||
key = derive_user_key(derivation_index)
|
||||
return PrivateKey(key.secret, compressed=True, network=PLM_MAINNET).wif(network=PLM_MAINNET)
|
||||
"""Exports a user's raw private key (WIF) for manual server-side intervention (e.g. sweeping funds back to a
|
||||
user, or out, if something gets stuck). Callers must treat the result as a live secret: log access, never
|
||||
persist it, never return it over an unauthenticated channel."""
|
||||
return engine.user_wif(_load_account_key(), derivation_index)
|
||||
|
||||
|
||||
def derive_pool_key(round_id: int | None = None) -> HDKey:
|
||||
"""A pool key. With a `round_id`, that round's own key on branch 2 of the account
|
||||
(`m/84'/746'/0'/2/<round_id>`, B-80, RND-35): its bets are paid to it and its
|
||||
payout is signed with it, so one round's money and history never mix with another's.
|
||||
Without one, the **reserve** key at branch 1, index 0 — the single pool address every
|
||||
round used before B-80, still the pool of the rounds opened back then and the
|
||||
destination of the payout's bump reserve. Branch 0 is users. Not a spec requirement
|
||||
of the coin, an implementation choice to keep every key under the one encrypted
|
||||
master key rather than in separate secrets."""
|
||||
if round_id is None:
|
||||
return _load_account_key().derive("1/0")
|
||||
if round_id < 1:
|
||||
raise ValueError(f"invalid round id {round_id}")
|
||||
return _load_account_key().derive(f"2/{round_id}")
|
||||
"""A pool key: a round's own (B-80, RND-35) or, without a `round_id`, the reserve key. See `plm_engine.hd`."""
|
||||
return engine.pool_key(_load_account_key(), round_id)
|
||||
|
||||
|
||||
def derive_pool_address(round_id: int | None = None) -> str:
|
||||
"""The pool address of a round (B-80), or the reserve address without a `round_id`."""
|
||||
pub = derive_pool_key(round_id).to_public()
|
||||
return script.p2wpkh(pub).address(network=PLM_MAINNET)
|
||||
return engine.pool_address(_load_account_key(), round_id)
|
||||
|
||||
|
||||
def derive_round_pool_key(round_id: int, pool_address: str) -> HDKey:
|
||||
"""The key that controls `pool_address`, the address stored on round `round_id`.
|
||||
|
||||
A round opened before B-80 stores the reserve address and is signed with the reserve
|
||||
key; every other round with its own. Checking the derived address against the stored
|
||||
one means a key can never be used for money it does not control, and a mismatch (a
|
||||
different master key, a corrupted row) fails loudly instead of building a transaction
|
||||
that spends someone else's coins."""
|
||||
for key in (derive_pool_key(round_id), derive_pool_key()):
|
||||
if script.p2wpkh(key.to_public()).address(network=PLM_MAINNET) == pool_address:
|
||||
return key
|
||||
raise ValueError(f"round {round_id}: no pool key controls the stored address {pool_address!r}")
|
||||
"""The key that controls `pool_address`, the address stored on round `round_id` (see `plm_engine.hd`)."""
|
||||
return engine.round_pool_key(_load_account_key(), round_id, pool_address)
|
||||
@@ -1,32 +0,0 @@
|
||||
"""PLM mainnet params for embit, verified against PalladiumWallet/src/Core/Chain/ChainProfiles.cs.
|
||||
|
||||
Threaded explicitly through every embit call via `network=PLM_MAINNET` rather than
|
||||
registered globally, since this is a long-lived async server (embit has no
|
||||
concept of "current network" beyond what you pass in).
|
||||
"""
|
||||
|
||||
PLM_MAINNET = {
|
||||
"name": "PLM Mainnet",
|
||||
"wif": bytes([0x80]),
|
||||
"p2pkh": bytes([55]),
|
||||
"p2sh": bytes([5]),
|
||||
"bech32": "plm",
|
||||
"xprv": bytes.fromhex("0488ade4"),
|
||||
"xpub": bytes.fromhex("0488b21e"),
|
||||
"yprv": bytes.fromhex("049d7878"),
|
||||
"ypub": bytes.fromhex("049d7cb2"),
|
||||
"zprv": bytes.fromhex("04b2430c"),
|
||||
"zpub": bytes.fromhex("04b24746"),
|
||||
"Yprv": bytes.fromhex("0295b005"),
|
||||
"Ypub": bytes.fromhex("0295b43f"),
|
||||
"Zprv": bytes.fromhex("02aa7a99"),
|
||||
"Zpub": bytes.fromhex("02aa7ed3"),
|
||||
"bip32": 0,
|
||||
}
|
||||
|
||||
BIP44_COIN_TYPE = 746
|
||||
ACCOUNT_PATH = f"m/84h/{BIP44_COIN_TYPE}h/0h"
|
||||
|
||||
# PLM shares Bitcoin's genesis block (palladiumcore chainparams.cpp) and its powLimit, so a
|
||||
# Bitcoin Electrum server would pass every header check; the handshake asks for this instead.
|
||||
GENESIS_HASH = "000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f"
|
||||
@@ -1,363 +0,0 @@
|
||||
from dataclasses import dataclass
|
||||
|
||||
from embit import script
|
||||
from embit.bip32 import HDKey
|
||||
from embit.finalizer import finalize_psbt
|
||||
from embit.psbt import PSBT
|
||||
from embit.transaction import Transaction, TransactionInput, TransactionOutput
|
||||
|
||||
# Standard P2WPKH size estimates (vbytes): 10.5-byte overhead (version+counts+locktime+
|
||||
# segwit marker/flag), ~68 vbytes per input, ~31 vbytes per output. Used to size the fee
|
||||
# before signing (fee only needs to be "minimized ~1 sat/vB", not maximally precise).
|
||||
_TX_OVERHEAD_VBYTES = 11
|
||||
_P2WPKH_INPUT_VBYTES = 68
|
||||
_P2WPKH_OUTPUT_VBYTES = 31
|
||||
|
||||
# BIP125 opt-in RBF: any sequence < 0xfffffffe signals replaceability. Set on every
|
||||
# input we create so a stuck tx can later be fee-bumped (tx/broadcast.py, stage 9).
|
||||
RBF_SEQUENCE = 0xFFFFFFFD
|
||||
|
||||
# Below this, an output costs more to spend than it's worth and relay policy rejects
|
||||
# the whole transaction as "dust" — so a small change amount must be left to the fee
|
||||
# instead of being paid back to ourselves. 294 sat is the standard P2WPKH threshold
|
||||
# (the output's own 31 vbytes plus the 67-vbyte input needed to spend it, at the
|
||||
# 3000 sat/kvB dust relay fee). Creating such an output used to make the bet or
|
||||
# withdrawal fail at broadcast with an opaque error (B-06).
|
||||
DUST_LIMIT_SATS = 294
|
||||
|
||||
# Sanity ceiling on any transaction's fee rate — shared by RoundConfig.fee_rate_sat_vb's
|
||||
# admin-facing bound (app/api/routes/admin.py, so the two can't drift apart, the same
|
||||
# reason MIN_PASSWORD_LENGTH is shared in auth/security.py) and tx/broadcast.py's RBF
|
||||
# bump escalation, which refuses to bump a pending_transaction past this rate (B-32) —
|
||||
# without a ceiling, a stuck transaction's fee climbed by 1 sat/vB every bump forever,
|
||||
# eating further and further into the sender's change with no limit. B-100: half of the node's own
|
||||
# `sendrawtransaction` maxfeerate (0.1 PLM/kvB = 10 000 sat/vB, palladiumcore rpc/rawtransaction.cpp):
|
||||
# vsize is estimated upwards, so a rate sitting exactly on the node's limit would be refused.
|
||||
MAX_FEE_RATE_SAT_VB = 5_000
|
||||
|
||||
# Ceiling on how many UTXOs one *user* transaction (bet, withdrawal) may spend (B-48).
|
||||
# Every extra input costs ~68 vbytes of fee, and that fee comes out of the amount being
|
||||
# moved — so an address fragmented into hundreds of small deposits would silently erode
|
||||
# its own bet (shrinking the user's share of the pool) or withdrawal. Failing the build
|
||||
# with a translatable error is the honest outcome; consolidating the address is the way
|
||||
# out. This is a *user-protection* limit, which is why the payout gets its own, far
|
||||
# higher one below.
|
||||
MAX_TX_INPUTS = 50
|
||||
|
||||
# Ceiling on the payout's inputs (B-52). The payout is not a user spending their own
|
||||
# fragmented balance: it drains the pool, whose UTXO count is simply the number of bets
|
||||
# in the round, and its fee comes out of a 70% share of that whole pool. So the erosion
|
||||
# argument behind MAX_TX_INPUTS doesn't apply here — 400 inputs at 1 sat/vB cost ~27_300
|
||||
# sat, i.e. ~0.00027 PLM out of the winner's share — and reusing that limit was what made
|
||||
# any round past ~50 participants unpayable: select_utxos raised too_many_inputs, the
|
||||
# round stayed "paying_out" retrying forever, and since no new round may open while one
|
||||
# is active, the whole lottery stopped with the pool stuck (B-52).
|
||||
#
|
||||
# What actually bounds this is relay policy: a non-standard transaction is refused at
|
||||
# broadcast past 100 kvB, which at ~68 vbytes per input is ~1470 inputs. 500 stays at
|
||||
# roughly a third of that budget, and signing that many inputs costs ~0.4s of event loop
|
||||
# (measured), once per round, inside a background task.
|
||||
MAX_PAYOUT_TX_INPUTS = 500
|
||||
|
||||
# The most participants one round may hold (B-52). Enforced where the money is not yet
|
||||
# committed — app/bets/service.py refuses the bet — instead of being discovered at payout
|
||||
# time, when the bets are already in the pool and there is no way back. Deliberately below
|
||||
# MAX_PAYOUT_TX_INPUTS: the payout also has to be able to spend whatever change UTXOs
|
||||
# earlier rounds left in the pool, so the gap is the headroom for those.
|
||||
MAX_PARTICIPANTS_PER_ROUND = 400
|
||||
|
||||
# B-79 (RND-38, DAT-73): every payout carries a bump reserve output, taken from the
|
||||
# platform's share and paid to the reserve address (m/84'/746'/0'/1/0). It is what an RBF
|
||||
# bump reduces: the pool normally holds exactly the round's bet outputs and the payout
|
||||
# spends them all, so without it the payout has no output to shrink, can never be bumped,
|
||||
# and one stuck in a mempool (which the reconciler never abandons while a server knows it)
|
||||
# kept the round in `paying_out` and the lottery stopped. 10 sat/vB is the rate the reserve
|
||||
# is sized to absorb, on top of the rate the payout was built at.
|
||||
PAYOUT_BUMP_RESERVE_SAT_VB = 10
|
||||
|
||||
|
||||
def payout_bump_reserve(n_inputs: int) -> int:
|
||||
"""The reserve output of a payout spending `n_inputs` coins (RND-38): enough to raise the
|
||||
fee of its three-output transaction to `PAYOUT_BUMP_RESERVE_SAT_VB`, and never below the
|
||||
dust limit (a smaller output would not be relayed)."""
|
||||
return max(DUST_LIMIT_SATS, estimate_vsize(n_inputs, 3) * PAYOUT_BUMP_RESERVE_SAT_VB)
|
||||
|
||||
|
||||
class InsufficientFundsError(Exception):
|
||||
"""`code` is the machine-readable identifier the API layer forwards to the
|
||||
client so it can translate the failure (see app/api/errors.py); the message
|
||||
itself stays English, and `params` carries the values it interpolates so the
|
||||
translation can place them wherever its own grammar needs them."""
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
message: str,
|
||||
code: str = "insufficient_balance",
|
||||
**params: int | str,
|
||||
) -> None:
|
||||
super().__init__(message)
|
||||
self.code = code
|
||||
self.params = params
|
||||
|
||||
|
||||
# B-73 (DAT-63): the recipient is always the first output of a single-recipient transaction
|
||||
# (the change, when there is one, follows it) — which is what a bet records as `bet_vout`.
|
||||
RECIPIENT_VOUT = 0
|
||||
|
||||
|
||||
@dataclass
|
||||
class Utxo:
|
||||
txid: str
|
||||
vout: int
|
||||
amount_sats: int
|
||||
|
||||
|
||||
@dataclass
|
||||
class BuiltTransaction:
|
||||
raw_hex: str
|
||||
txid: str
|
||||
fee_sats: int
|
||||
recipient_sats: int
|
||||
change_sats: int
|
||||
spent_utxos: list[Utxo]
|
||||
|
||||
|
||||
def estimate_vsize(n_inputs: int, n_outputs: int) -> int:
|
||||
return _TX_OVERHEAD_VBYTES + n_inputs * _P2WPKH_INPUT_VBYTES + n_outputs * _P2WPKH_OUTPUT_VBYTES
|
||||
|
||||
|
||||
def select_utxos(
|
||||
utxos: list[Utxo], target_sats: int, max_inputs: int = MAX_TX_INPUTS, min_change_sats: int = 0
|
||||
) -> tuple[list[Utxo], int]:
|
||||
"""Greedily select UTXOs (largest first, to minimize input count) covering
|
||||
target_sats — the amount deducted from the sender's balance. The fee is paid
|
||||
out of target_sats (see build_signed_transaction), not added on top of it.
|
||||
|
||||
At most `max_inputs` are ever selected (B-48): if the largest `max_inputs`
|
||||
UTXOs don't cover the target, the balance is there but too fragmented to spend
|
||||
in one transaction, which is a different failure from having no funds at all
|
||||
and gets its own code.
|
||||
|
||||
The cap is a parameter, not the constant it used to be, because the two callers
|
||||
want different ones (B-52): MAX_TX_INPUTS protects a user from a fee that would
|
||||
eat into their own bet/withdrawal, while the payout drains a pool holding one
|
||||
UTXO per bet and needs MAX_PAYOUT_TX_INPUTS to be able to pay a full round at
|
||||
all.
|
||||
|
||||
B-98 (BET-24): with `min_change_sats` selection goes on until the total covers
|
||||
`target + min_change_sats`, so a second coin is taken when the first covers the
|
||||
target exactly. Only when every allowed coin together cannot leave that change is
|
||||
the shorter selection returned (any total >= target), and the caller then refuses
|
||||
the bet or reduces the withdrawal as before."""
|
||||
# B-75: a UTXO below the dust limit is never offered, even if one is already on
|
||||
# record: it costs more to spend than it is worth.
|
||||
ordered = sorted(
|
||||
(u for u in utxos if u.amount_sats >= DUST_LIMIT_SATS), key=lambda u: u.amount_sats, reverse=True
|
||||
)
|
||||
selected: list[Utxo] = []
|
||||
total = 0
|
||||
for utxo in ordered:
|
||||
if total >= target_sats + min_change_sats or len(selected) == max_inputs:
|
||||
break
|
||||
selected.append(utxo)
|
||||
total += utxo.amount_sats
|
||||
if total >= target_sats:
|
||||
return selected, total
|
||||
if len(selected) == max_inputs and len(ordered) > max_inputs:
|
||||
raise InsufficientFundsError(
|
||||
f"balance too fragmented: more than {max_inputs} inputs would be needed",
|
||||
code="too_many_inputs",
|
||||
max_inputs=max_inputs,
|
||||
)
|
||||
raise InsufficientFundsError("not enough confirmed balance to cover amount")
|
||||
|
||||
|
||||
def build_signed_transaction(
|
||||
*,
|
||||
signing_key: HDKey,
|
||||
from_script: script.Script,
|
||||
utxos: list[Utxo],
|
||||
to_address: str,
|
||||
amount_sats: int,
|
||||
change_address: str,
|
||||
fee_rate_sat_vb: int,
|
||||
reduce_amount_to_keep_change: bool = False,
|
||||
) -> BuiltTransaction:
|
||||
"""Build, sign and finalize a single-recipient P2WPKH transaction with change
|
||||
back to change_address.
|
||||
|
||||
`amount_sats` is deducted from the sender's balance in full: the recipient
|
||||
receives `amount_sats - fee`, change = total_in - amount_sats. This matches the
|
||||
spec everywhere a single-recipient tx is used (bet, withdrawal): "fee deducted
|
||||
from the amount being moved", not paid on top by the sender.
|
||||
|
||||
B-62: the transaction always keeps a change output of at least DUST_LIMIT_SATS.
|
||||
Change used to be folded into the fee whenever it came out below the dust limit,
|
||||
which for an amount equal to the whole input total (the UI's "withdraw
|
||||
everything" checkbox, or a bet from a balance exactly equal to the bet amount)
|
||||
produced a single-output transaction — and `tx/broadcast.py:bump_fee` has nothing
|
||||
to shrink there, so it raised RbfError every 30s until the reconciler abandoned
|
||||
the row hours later. Adding inputs instead is no answer for this case in
|
||||
particular: the transaction already spends every UTXO the sender has.
|
||||
|
||||
What happens when the change would be too small depends on who's asking, hence
|
||||
`reduce_amount_to_keep_change`:
|
||||
|
||||
- withdrawals pass True — the amount moved is reduced just enough to leave a
|
||||
dust-limit change output. The fee already comes out of the withdrawn amount by
|
||||
design, so this is the same rule applied a little harder, and the caller
|
||||
records what was actually sent (`Withdrawal.amount_sent_sats`).
|
||||
- bets pass False (the default) and get an InsufficientFundsError instead: the
|
||||
bet is a fixed price that cannot be quietly reduced, and "a user's balance must
|
||||
never exactly equal the bet" is a documented invariant of the PLAY phase. The
|
||||
player needs a little more than the bet amount, which is what the error says.
|
||||
"""
|
||||
selected, total_in = select_utxos(utxos, amount_sats, min_change_sats=DUST_LIMIT_SATS)
|
||||
fee = estimate_vsize(len(selected), 2) * fee_rate_sat_vb
|
||||
|
||||
change = total_in - amount_sats
|
||||
if change < DUST_LIMIT_SATS:
|
||||
if not reduce_amount_to_keep_change:
|
||||
raise InsufficientFundsError(
|
||||
f"the amount leaves no change output: {DUST_LIMIT_SATS - change} more sats are "
|
||||
"needed for the transaction to stay fee-bumpable",
|
||||
code="balance_leaves_no_change",
|
||||
required_extra_sats=DUST_LIMIT_SATS - change,
|
||||
)
|
||||
amount_sats -= DUST_LIMIT_SATS - change
|
||||
change = DUST_LIMIT_SATS
|
||||
|
||||
recipient_amount = amount_sats - fee
|
||||
if recipient_amount <= 0:
|
||||
raise InsufficientFundsError(
|
||||
"amount too small to cover the network fee", code="amount_below_network_fee"
|
||||
)
|
||||
if recipient_amount < DUST_LIMIT_SATS:
|
||||
raise InsufficientFundsError(
|
||||
"amount too small to be sent (dust)", code="amount_below_dust_limit"
|
||||
)
|
||||
|
||||
# TransactionInput.txid is natural/display byte order (as in tx_hash from Electrum);
|
||||
# embit reverses it internally when serializing to wire format.
|
||||
vin = [TransactionInput(bytes.fromhex(u.txid), u.vout, sequence=RBF_SEQUENCE) for u in selected]
|
||||
vout = [TransactionOutput(recipient_amount, script.Script.from_address(to_address))]
|
||||
if change > 0:
|
||||
vout.append(TransactionOutput(change, script.Script.from_address(change_address)))
|
||||
|
||||
tx = Transaction(vin=vin, vout=vout)
|
||||
psbt = PSBT(tx)
|
||||
for i, utxo in enumerate(selected):
|
||||
psbt.inputs[i].witness_utxo = TransactionOutput(utxo.amount_sats, from_script)
|
||||
|
||||
signed_count = psbt.sign_with(signing_key)
|
||||
if signed_count != len(selected):
|
||||
raise RuntimeError(f"expected {len(selected)} signatures, got {signed_count}")
|
||||
|
||||
final_tx = finalize_psbt(psbt)
|
||||
if final_tx is None:
|
||||
raise RuntimeError("failed to finalize PSBT")
|
||||
|
||||
raw = final_tx.serialize()
|
||||
return BuiltTransaction(
|
||||
raw_hex=raw.hex(),
|
||||
txid=final_tx.txid().hex(),
|
||||
fee_sats=fee,
|
||||
recipient_sats=recipient_amount,
|
||||
change_sats=change,
|
||||
spent_utxos=selected,
|
||||
)
|
||||
|
||||
|
||||
@dataclass
|
||||
class PayoutTransaction:
|
||||
raw_hex: str
|
||||
txid: str
|
||||
fee_sats: int
|
||||
winner_sats: int
|
||||
commission_sats: int # what the fee address receives: the platform share minus the reserve
|
||||
reserve_sats: int # B-79: the bump reserve output (plus any excess input value, see below)
|
||||
change_sats: int # inputs beyond winner share + commission, folded into the reserve output
|
||||
spent_utxos: list[Utxo]
|
||||
|
||||
|
||||
def build_payout_transaction(
|
||||
*,
|
||||
signing_key: HDKey,
|
||||
from_script: script.Script,
|
||||
utxos: list[Utxo],
|
||||
winner_address: str,
|
||||
winner_share_sats: int,
|
||||
fee_address: str,
|
||||
commission_sats: int,
|
||||
reserve_address: str,
|
||||
fee_rate_sat_vb: int,
|
||||
) -> PayoutTransaction:
|
||||
"""Build, sign and finalize the round payout: pool -> winner + fee address + reserve.
|
||||
|
||||
B-79 (RND-21, RND-23, RND-38): three outputs, always. `commission_sats` is the platform's
|
||||
whole share (30% plus the rounding remainder); the bump reserve (`payout_bump_reserve`)
|
||||
is taken out of it and paid to `reserve_address`, the output an RBF bump will shrink
|
||||
(TX-11), and the fee address receives the rest. Per spec, only the winner's share
|
||||
absorbs the network fee — never the platform's.
|
||||
|
||||
Inputs beyond winner share + commission exist only for rounds opened before the
|
||||
per-round pool address (the shared pool held other money): that excess is folded into
|
||||
the reserve output if it is at least the dust limit, and left to the network fee
|
||||
otherwise, as in build_signed_transaction (B-06).
|
||||
|
||||
Selection uses MAX_PAYOUT_TX_INPUTS, not the much stricter user-facing
|
||||
MAX_TX_INPUTS (B-52) — the pool holds one UTXO per bet, so the user-protection
|
||||
cap made every round past ~50 participants impossible to pay."""
|
||||
target = winner_share_sats + commission_sats
|
||||
selected, total_in = select_utxos(utxos, target, max_inputs=MAX_PAYOUT_TX_INPUTS)
|
||||
fee = estimate_vsize(len(selected), 3) * fee_rate_sat_vb # winner + fee address + reserve
|
||||
winner_amount = winner_share_sats - fee
|
||||
if winner_amount < DUST_LIMIT_SATS:
|
||||
raise InsufficientFundsError(
|
||||
"winner share too small to cover the network fee", code="winner_share_below_network_fee"
|
||||
)
|
||||
reserve = payout_bump_reserve(len(selected))
|
||||
fee_address_amount = commission_sats - reserve
|
||||
if fee_address_amount < DUST_LIMIT_SATS:
|
||||
raise InsufficientFundsError(
|
||||
"commission share too small to cover the bump reserve and still be paid out (dust)",
|
||||
code="commission_below_dust_limit",
|
||||
)
|
||||
excess = total_in - target
|
||||
if excess >= DUST_LIMIT_SATS:
|
||||
reserve += excess
|
||||
else:
|
||||
fee += excess
|
||||
excess = 0
|
||||
|
||||
vin = [TransactionInput(bytes.fromhex(u.txid), u.vout, sequence=RBF_SEQUENCE) for u in selected]
|
||||
vout = [
|
||||
TransactionOutput(winner_amount, script.Script.from_address(winner_address)),
|
||||
TransactionOutput(fee_address_amount, script.Script.from_address(fee_address)),
|
||||
TransactionOutput(reserve, script.Script.from_address(reserve_address)),
|
||||
]
|
||||
|
||||
tx = Transaction(vin=vin, vout=vout)
|
||||
psbt = PSBT(tx)
|
||||
for i, utxo in enumerate(selected):
|
||||
psbt.inputs[i].witness_utxo = TransactionOutput(utxo.amount_sats, from_script)
|
||||
|
||||
signed_count = psbt.sign_with(signing_key)
|
||||
if signed_count != len(selected):
|
||||
raise RuntimeError(f"expected {len(selected)} signatures, got {signed_count}")
|
||||
|
||||
final_tx = finalize_psbt(psbt)
|
||||
if final_tx is None:
|
||||
raise RuntimeError("failed to finalize PSBT")
|
||||
|
||||
raw = final_tx.serialize()
|
||||
return PayoutTransaction(
|
||||
raw_hex=raw.hex(),
|
||||
txid=final_tx.txid().hex(),
|
||||
fee_sats=fee,
|
||||
winner_sats=winner_amount,
|
||||
commission_sats=fee_address_amount,
|
||||
reserve_sats=reserve,
|
||||
change_sats=excess,
|
||||
spent_utxos=selected,
|
||||
)
|
||||
@@ -16,7 +16,7 @@ from embit import script
|
||||
from embit.bip32 import HDKey
|
||||
|
||||
from app.config import ConfigError, settings
|
||||
from app.wallet.plm_network import ACCOUNT_PATH, PLM_MAINNET
|
||||
from plm_engine.network import ACCOUNT_PATH, PLM_MAINNET
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
@@ -10,15 +10,15 @@ from app.api.errors import ApiError
|
||||
from app.audit.log import write_audit_log
|
||||
from app.db.base import begin_immediate
|
||||
from app.db.models import PendingTransaction, Round, User, UtxoEvent, Withdrawal
|
||||
from app.electrum.client import ElectrumClient
|
||||
from plm_engine.electrum.client import ElectrumClient
|
||||
from app.rounds.config import get_round_config
|
||||
from app.rounds.events import broadcaster
|
||||
from app.tx.versions import record_version
|
||||
from app.tx.outcome import BroadcastOutcome, TransactionNetwork, broadcast_with_verdict
|
||||
from app.wallet.address import is_valid_plm_address
|
||||
from plm_engine.address import is_valid_plm_address
|
||||
from app.wallet.balance import compute_pending_balance, recompute_balance
|
||||
from app.wallet.hd import derive_pool_address, derive_user_key
|
||||
from app.wallet.psbt_builder import (
|
||||
from plm_engine.psbt_builder import (
|
||||
BuiltTransaction,
|
||||
InsufficientFundsError,
|
||||
Utxo,
|
||||
|
||||
Reference in new issue
Block a user