B4: chain tables, HD index assignment and signing key reserved to the worker (DAT-81..84, ARC-78)
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
0092596b07
commit
f1d09075a1
18 files changed
+741
-8
No files matched your search
@@ -9,7 +9,9 @@ from .simulation import simulated_address
|
||||
def participant_address(user) -> str:
|
||||
if settings.LEDGER_BACKEND == "simulated":
|
||||
return simulated_address(user)
|
||||
raise NotImplementedError("HD addresses arrive with phase B (roadmap B4)")
|
||||
from .chain import assign_deposit_address
|
||||
|
||||
return assign_deposit_address(user).address
|
||||
|
||||
|
||||
def is_valid_address(address: str) -> bool:
|
||||
|
||||
@@ -0,0 +1,62 @@
|
||||
"""Services over the chain tables (roadmap B4): the HD index of a deposit address (DAT-81) and the versions of a
|
||||
transaction (DAT-83). Uniqueness is decided by the database, never by a read followed by a write (ARC-72)."""
|
||||
|
||||
from django.conf import settings
|
||||
from django.db import IntegrityError, transaction
|
||||
from django.db.models import Max
|
||||
from plm_engine import hd
|
||||
|
||||
from . import keys
|
||||
from .models import ChainTransaction, DepositAddress, TransactionVersion
|
||||
|
||||
_ATTEMPTS = 20
|
||||
|
||||
|
||||
class TxidConflict(Exception):
|
||||
"""The txid already belongs to another platform transaction (DAT-83)."""
|
||||
|
||||
|
||||
def derive_deposit_address(index: int) -> str:
|
||||
"""The address for an HD index: a pure function of the public key, the index and the network."""
|
||||
return hd.user_address(keys.public_account_key(), index, settings.PLM_PROFILE)
|
||||
|
||||
|
||||
def assign_deposit_address(user) -> DepositAddress:
|
||||
"""The player's deposit address; created on first use, the same one ever after (DAT-81). The index is the
|
||||
next after the highest assigned; if a concurrent assignment takes it first the unique index refuses ours
|
||||
and we take the next one."""
|
||||
existing = DepositAddress.objects.filter(user=user).first()
|
||||
if existing is not None:
|
||||
return existing
|
||||
for _ in range(_ATTEMPTS):
|
||||
try:
|
||||
with transaction.atomic():
|
||||
top = DepositAddress.objects.aggregate(top=Max("derivation_index"))["top"]
|
||||
index = 0 if top is None else top + 1
|
||||
return DepositAddress.objects.create(
|
||||
user=user, derivation_index=index, address=derive_deposit_address(index), network=settings.PLM_NETWORK
|
||||
)
|
||||
except IntegrityError:
|
||||
raced = DepositAddress.objects.filter(user=user).first() # the same player assigned twice at once
|
||||
if raced is not None:
|
||||
return raced
|
||||
raise RuntimeError("could not assign a deposit address: too many concurrent assignments")
|
||||
|
||||
|
||||
def register_version(tx: ChainTransaction, txid: str, raw_hex: str = "") -> TransactionVersion:
|
||||
"""Record a txid of `tx` and make it the current one (DAT-83, TX-19). Idempotent for the same pair; a txid of
|
||||
another transaction is refused. One database transaction, so the version and `current_txid` agree."""
|
||||
with transaction.atomic():
|
||||
existing = TransactionVersion.objects.filter(txid=txid).first()
|
||||
if existing is not None:
|
||||
if existing.transaction_id != tx.pk:
|
||||
raise TxidConflict(f"{txid} belongs to transaction {existing.transaction_id}")
|
||||
version = existing
|
||||
else:
|
||||
version = TransactionVersion.objects.create(transaction=tx, txid=txid, raw_hex=raw_hex)
|
||||
if tx.current_txid != txid:
|
||||
tx.current_txid = txid
|
||||
if raw_hex:
|
||||
tx.raw_hex = raw_hex
|
||||
tx.save(update_fields=["current_txid", "raw_hex"])
|
||||
return version
|
||||
@@ -0,0 +1,66 @@
|
||||
"""Who may hold which key (ARC-78, roadmap B4).
|
||||
|
||||
The web process knows only the **public** account key (`PLM_ACCOUNT_XPUB`): it is enough to derive every deposit
|
||||
and pool address. The private side — the master xprv, encrypted, and the key that encrypts it, two separate files —
|
||||
is loaded only by the worker (`PROCESS_ROLE=worker`) and only when both files are there. Anywhere else the loader
|
||||
refuses, whatever the files, so a bug in a view cannot reach the signing key.
|
||||
"""
|
||||
|
||||
import os
|
||||
from pathlib import Path
|
||||
|
||||
from cryptography.fernet import Fernet, InvalidToken
|
||||
from django.conf import settings
|
||||
from embit.bip32 import HDKey
|
||||
from plm_engine.network import Profile
|
||||
|
||||
|
||||
class SigningKeyUnavailable(Exception):
|
||||
pass
|
||||
|
||||
|
||||
def public_account_key() -> HDKey:
|
||||
"""The account's public key, from configuration: derives addresses, signs nothing."""
|
||||
xpub = settings.PLM_ACCOUNT_XPUB
|
||||
if not xpub:
|
||||
raise SigningKeyUnavailable("PLM_ACCOUNT_XPUB is not set: run `manage.py init_keys` and put the public key in .env")
|
||||
return HDKey.from_base58(xpub)
|
||||
|
||||
|
||||
def signing_account_key() -> HDKey:
|
||||
"""The private account key. Only the worker can have it."""
|
||||
if settings.PROCESS_ROLE != "worker":
|
||||
raise SigningKeyUnavailable("the signing key is only available to the worker process")
|
||||
master_file, key_file = settings.PLM_MASTER_KEY_FILE, settings.PLM_KEY_ENCRYPTION_KEY_FILE
|
||||
if not (master_file and key_file):
|
||||
raise SigningKeyUnavailable("PLM_MASTER_KEY_FILE and PLM_KEY_ENCRYPTION_KEY_FILE are not set")
|
||||
try:
|
||||
token = Path(master_file).read_bytes()
|
||||
fernet = Fernet(Path(key_file).read_bytes().strip())
|
||||
master = HDKey.from_base58(fernet.decrypt(token).decode())
|
||||
except (OSError, InvalidToken, ValueError) as exc:
|
||||
raise SigningKeyUnavailable(f"the signing key cannot be loaded: {exc.__class__.__name__}") from exc
|
||||
return master.derive(settings.PLM_PROFILE.account_path)
|
||||
|
||||
|
||||
def _write_private(path: Path, data: bytes) -> None:
|
||||
"""`0600` from the start, never through a wider mode (SEC-50)."""
|
||||
fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
|
||||
with os.fdopen(fd, "wb") as handle:
|
||||
os.fchmod(handle.fileno(), 0o600)
|
||||
handle.write(data)
|
||||
|
||||
|
||||
def generate_keys(directory: Path, profile: Profile) -> str:
|
||||
"""Create a master key and its encryption key under `directory` (refuses to overwrite) and return the
|
||||
account's public key, to be put in `PLM_ACCOUNT_XPUB`."""
|
||||
directory.mkdir(parents=True, exist_ok=True, mode=0o700)
|
||||
master_path, key_path = directory / "master.key", directory / "master.encryption.key"
|
||||
if master_path.exists() or key_path.exists():
|
||||
raise FileExistsError(f"{directory} already holds keys: refusing to overwrite them")
|
||||
master = HDKey.from_seed(os.urandom(32), version=profile.embit["xprv"])
|
||||
encryption_key = Fernet.generate_key()
|
||||
_write_private(key_path, encryption_key)
|
||||
_write_private(master_path, Fernet(encryption_key).encrypt(master.to_base58(version=profile.embit["xprv"]).encode()))
|
||||
account = master.derive(profile.account_path).to_public()
|
||||
return account.to_base58(version=profile.embit["xpub"])
|
||||
@@ -0,0 +1,22 @@
|
||||
from pathlib import Path
|
||||
|
||||
from django.conf import settings
|
||||
from django.core.management.base import BaseCommand, CommandError
|
||||
|
||||
from apps.lottery.keys import generate_keys
|
||||
|
||||
|
||||
class Command(BaseCommand):
|
||||
help = "One-off: create the master key and its encryption key (0600) and print the account's public key (ARC-78)."
|
||||
|
||||
def add_arguments(self, parser):
|
||||
parser.add_argument("directory", help="where to write master.key and master.encryption.key")
|
||||
|
||||
def handle(self, *args, **options):
|
||||
try:
|
||||
xpub = generate_keys(Path(options["directory"]), settings.PLM_PROFILE)
|
||||
except FileExistsError as error:
|
||||
raise CommandError(str(error)) from error
|
||||
self.stdout.write(f"Keys written to {options['directory']} for {settings.PLM_NETWORK}.")
|
||||
self.stdout.write("Put this public key in .env (the web process needs nothing else):")
|
||||
self.stdout.write(f"PLM_ACCOUNT_XPUB={xpub}")
|
||||
@@ -0,0 +1,110 @@
|
||||
# Generated by Django 5.2.19 on 2026-11-16 14:50
|
||||
|
||||
import django.db.models.deletion
|
||||
import django.db.models.functions.text
|
||||
import django.db.models.lookups
|
||||
import django.utils.timezone
|
||||
from django.conf import settings
|
||||
from django.db import migrations, models
|
||||
|
||||
|
||||
class Migration(migrations.Migration):
|
||||
|
||||
dependencies = [
|
||||
('lottery', '0003_console_and_reports'),
|
||||
migrations.swappable_dependency(settings.AUTH_USER_MODEL),
|
||||
]
|
||||
|
||||
operations = [
|
||||
migrations.CreateModel(
|
||||
name='Utxo',
|
||||
fields=[
|
||||
('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
|
||||
('txid', models.CharField(max_length=64)),
|
||||
('vout', models.PositiveIntegerField()),
|
||||
('amount_sats', models.BigIntegerField()),
|
||||
('address', models.CharField(max_length=128)),
|
||||
('confirmed_height', models.PositiveIntegerField(blank=True, null=True)),
|
||||
('spent_txid', models.CharField(blank=True, max_length=64, null=True)),
|
||||
('created_at', models.DateTimeField(default=django.utils.timezone.now)),
|
||||
('reserved_by', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.PROTECT, related_name='reserved_utxos', to='lottery.chaintransaction')),
|
||||
('round', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.PROTECT, related_name='utxos', to='lottery.round')),
|
||||
('user', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.PROTECT, related_name='utxos', to=settings.AUTH_USER_MODEL)),
|
||||
],
|
||||
),
|
||||
migrations.CreateModel(
|
||||
name='Deposit',
|
||||
fields=[
|
||||
('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
|
||||
('status', models.CharField(choices=[('detected', 'Detected'), ('credited', 'Credited'), ('orphaned', 'Orphaned')], default='detected', max_length=16)),
|
||||
('detected_at', models.DateTimeField(default=django.utils.timezone.now)),
|
||||
('credited_at', models.DateTimeField(blank=True, null=True)),
|
||||
('movement', models.OneToOneField(blank=True, null=True, on_delete=django.db.models.deletion.PROTECT, related_name='deposit', to='lottery.movement')),
|
||||
('user', models.ForeignKey(on_delete=django.db.models.deletion.PROTECT, related_name='deposits', to=settings.AUTH_USER_MODEL)),
|
||||
('utxo', models.OneToOneField(on_delete=django.db.models.deletion.PROTECT, related_name='deposit', to='lottery.utxo')),
|
||||
],
|
||||
),
|
||||
migrations.CreateModel(
|
||||
name='DepositAddress',
|
||||
fields=[
|
||||
('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
|
||||
('derivation_index', models.PositiveIntegerField(unique=True)),
|
||||
('address', models.CharField(max_length=128, unique=True)),
|
||||
('network', models.CharField(max_length=16)),
|
||||
('created_at', models.DateTimeField(default=django.utils.timezone.now)),
|
||||
('user', models.OneToOneField(on_delete=django.db.models.deletion.PROTECT, related_name='deposit_address', to=settings.AUTH_USER_MODEL)),
|
||||
],
|
||||
options={
|
||||
'constraints': [models.CheckConstraint(condition=models.Q(('network__in', ['mainnet', 'regtest'])), name='lottery_depositaddress_network_valid')],
|
||||
},
|
||||
),
|
||||
migrations.CreateModel(
|
||||
name='TransactionVersion',
|
||||
fields=[
|
||||
('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
|
||||
('txid', models.CharField(max_length=64, unique=True)),
|
||||
('raw_hex', models.TextField(blank=True, default='')),
|
||||
('created_at', models.DateTimeField(default=django.utils.timezone.now)),
|
||||
('transaction', models.ForeignKey(on_delete=django.db.models.deletion.PROTECT, related_name='versions', to='lottery.chaintransaction')),
|
||||
],
|
||||
options={
|
||||
'constraints': [models.CheckConstraint(condition=django.db.models.lookups.Exact(django.db.models.functions.text.Length('txid'), 64), name='lottery_txversion_txid_length')],
|
||||
},
|
||||
),
|
||||
migrations.AddIndex(
|
||||
model_name='utxo',
|
||||
index=models.Index(fields=['address'], name='lottery_utx_address_daa4dd_idx'),
|
||||
),
|
||||
migrations.AddIndex(
|
||||
model_name='utxo',
|
||||
index=models.Index(fields=['user'], name='lottery_utx_user_id_2ccdc9_idx'),
|
||||
),
|
||||
migrations.AddConstraint(
|
||||
model_name='utxo',
|
||||
constraint=models.UniqueConstraint(fields=('txid', 'vout'), name='lottery_utxo_outpoint_unique'),
|
||||
),
|
||||
migrations.AddConstraint(
|
||||
model_name='utxo',
|
||||
constraint=models.CheckConstraint(condition=models.Q(('amount_sats__gt', 0)), name='lottery_utxo_amount_positive'),
|
||||
),
|
||||
migrations.AddConstraint(
|
||||
model_name='utxo',
|
||||
constraint=models.CheckConstraint(condition=django.db.models.lookups.Exact(django.db.models.functions.text.Length('txid'), 64), name='lottery_utxo_txid_length'),
|
||||
),
|
||||
migrations.AddConstraint(
|
||||
model_name='utxo',
|
||||
constraint=models.CheckConstraint(condition=models.Q(('spent_txid__isnull', True), django.db.models.lookups.Exact(django.db.models.functions.text.Length('spent_txid'), 64), _connector='OR'), name='lottery_utxo_spent_txid_length'),
|
||||
),
|
||||
migrations.AddConstraint(
|
||||
model_name='utxo',
|
||||
constraint=models.CheckConstraint(condition=models.Q(('user__isnull', True), ('round__isnull', True), _connector='OR'), name='lottery_utxo_user_or_round'),
|
||||
),
|
||||
migrations.AddConstraint(
|
||||
model_name='deposit',
|
||||
constraint=models.CheckConstraint(condition=models.Q(('status__in', ['detected', 'credited', 'orphaned'])), name='lottery_deposit_status_valid'),
|
||||
),
|
||||
migrations.AddConstraint(
|
||||
model_name='deposit',
|
||||
constraint=models.CheckConstraint(condition=models.Q(models.Q(('status', 'credited'), _negated=True), models.Q(('movement__isnull', False), ('credited_at__isnull', False)), _connector='OR'), name='lottery_deposit_credited_has_movement'),
|
||||
),
|
||||
]
|
||||
@@ -0,0 +1,20 @@
|
||||
"""Transaction versions are append-only in the database too (DAT-83): a raw `UPDATE` or `DELETE` is refused.
|
||||
SQLite syntax, like the audit triggers (ADR-55)."""
|
||||
|
||||
from django.db import migrations
|
||||
|
||||
CREATE = [
|
||||
"""CREATE TRIGGER lottery_txversion_no_update BEFORE UPDATE ON lottery_transactionversion
|
||||
BEGIN SELECT RAISE(ABORT, 'transaction versions are append-only'); END""",
|
||||
"""CREATE TRIGGER lottery_txversion_no_delete BEFORE DELETE ON lottery_transactionversion
|
||||
BEGIN SELECT RAISE(ABORT, 'transaction versions are append-only'); END""",
|
||||
]
|
||||
DROP = [
|
||||
"DROP TRIGGER IF EXISTS lottery_txversion_no_update",
|
||||
"DROP TRIGGER IF EXISTS lottery_txversion_no_delete",
|
||||
]
|
||||
|
||||
|
||||
class Migration(migrations.Migration):
|
||||
dependencies = [("lottery", "0004_chain_tables")]
|
||||
operations = [migrations.RunSQL(sql=CREATE, reverse_sql=DROP)]
|
||||
@@ -11,6 +11,8 @@ Rows that carry money are never deleted: every foreign key is PROTECT (DAT-76).
|
||||
from django.conf import settings
|
||||
from django.db import models
|
||||
from django.db.models import F, Q, Value
|
||||
from django.db.models.functions import Length
|
||||
from django.db.models.lookups import Exact
|
||||
from django.utils import timezone
|
||||
|
||||
SATS_PER_PLM = 100_000_000
|
||||
@@ -420,3 +422,124 @@ class Report(models.Model):
|
||||
|
||||
def __str__(self) -> str:
|
||||
return f"Report {self.pk} ({self.status})"
|
||||
|
||||
|
||||
# --- chain tables (roadmap B4, DAT-81..DAT-84) ---------------------------------------------------
|
||||
|
||||
|
||||
class DepositAddress(models.Model):
|
||||
"""A player's one deposit address and the HD index it comes from (DAT-81)."""
|
||||
|
||||
user = models.OneToOneField(settings.AUTH_USER_MODEL, on_delete=models.PROTECT, related_name="deposit_address")
|
||||
derivation_index = models.PositiveIntegerField(unique=True)
|
||||
address = models.CharField(max_length=128, unique=True)
|
||||
network = models.CharField(max_length=16) # the profile it was derived for (ADR-58)
|
||||
created_at = models.DateTimeField(default=timezone.now)
|
||||
|
||||
class Meta:
|
||||
constraints = [
|
||||
models.CheckConstraint(condition=Q(network__in=["mainnet", "regtest"]), name="lottery_depositaddress_network_valid"),
|
||||
]
|
||||
|
||||
def __str__(self) -> str:
|
||||
return f"{self.address} (index {self.derivation_index})"
|
||||
|
||||
|
||||
class Utxo(models.Model):
|
||||
"""An output the platform controls (DAT-82): a player's deposit or a round's pool money."""
|
||||
|
||||
txid = models.CharField(max_length=64)
|
||||
vout = models.PositiveIntegerField()
|
||||
amount_sats = models.BigIntegerField()
|
||||
address = models.CharField(max_length=128)
|
||||
user = models.ForeignKey(settings.AUTH_USER_MODEL, null=True, blank=True, on_delete=models.PROTECT, related_name="utxos")
|
||||
round = models.ForeignKey(Round, null=True, blank=True, on_delete=models.PROTECT, related_name="utxos")
|
||||
confirmed_height = models.PositiveIntegerField(null=True, blank=True)
|
||||
spent_txid = models.CharField(max_length=64, null=True, blank=True)
|
||||
# ARC-72: the transaction that is spending it. Taken atomically in the database, never in memory (B6).
|
||||
reserved_by = models.ForeignKey(
|
||||
ChainTransaction, null=True, blank=True, on_delete=models.PROTECT, related_name="reserved_utxos"
|
||||
)
|
||||
created_at = models.DateTimeField(default=timezone.now)
|
||||
|
||||
class Meta:
|
||||
indexes = [models.Index(fields=["address"]), models.Index(fields=["user"])]
|
||||
constraints = [
|
||||
models.UniqueConstraint(fields=["txid", "vout"], name="lottery_utxo_outpoint_unique"),
|
||||
models.CheckConstraint(condition=Q(amount_sats__gt=0), name="lottery_utxo_amount_positive"),
|
||||
models.CheckConstraint(condition=Exact(Length("txid"), 64), name="lottery_utxo_txid_length"),
|
||||
models.CheckConstraint(
|
||||
condition=Q(spent_txid__isnull=True) | Q(Exact(Length("spent_txid"), 64)), name="lottery_utxo_spent_txid_length"
|
||||
),
|
||||
models.CheckConstraint(condition=Q(user__isnull=True) | Q(round__isnull=True), name="lottery_utxo_user_or_round"),
|
||||
]
|
||||
|
||||
def __str__(self) -> str:
|
||||
return f"{self.txid[:12]}:{self.vout}"
|
||||
|
||||
|
||||
class TransactionVersionImmutable(Exception):
|
||||
"""An attempt to change or delete a transaction version (DAT-83)."""
|
||||
|
||||
|
||||
class TransactionVersionQuerySet(models.QuerySet):
|
||||
def update(self, **kwargs):
|
||||
raise TransactionVersionImmutable("transaction versions are append-only")
|
||||
|
||||
def delete(self):
|
||||
raise TransactionVersionImmutable("transaction versions are append-only")
|
||||
|
||||
|
||||
class TransactionVersion(models.Model):
|
||||
"""Every txid a platform transaction has ever had (TX-19, DAT-83): the network may confirm any of them."""
|
||||
|
||||
transaction = models.ForeignKey(ChainTransaction, on_delete=models.PROTECT, related_name="versions")
|
||||
txid = models.CharField(max_length=64, unique=True)
|
||||
raw_hex = models.TextField(blank=True, default="")
|
||||
created_at = models.DateTimeField(default=timezone.now)
|
||||
|
||||
objects = TransactionVersionQuerySet.as_manager()
|
||||
|
||||
class Meta:
|
||||
constraints = [models.CheckConstraint(condition=Exact(Length("txid"), 64), name="lottery_txversion_txid_length")]
|
||||
|
||||
def save(self, *args, **kwargs):
|
||||
if not self._state.adding:
|
||||
raise TransactionVersionImmutable("transaction versions are append-only")
|
||||
super().save(*args, **kwargs)
|
||||
|
||||
def delete(self, *args, **kwargs):
|
||||
raise TransactionVersionImmutable("transaction versions are append-only")
|
||||
|
||||
def __str__(self) -> str:
|
||||
return self.txid
|
||||
|
||||
|
||||
class Deposit(models.Model):
|
||||
"""An output that paid a player's deposit address (DAT-84)."""
|
||||
|
||||
class Status(models.TextChoices):
|
||||
DETECTED = "detected"
|
||||
CREDITED = "credited"
|
||||
ORPHANED = "orphaned"
|
||||
|
||||
user = models.ForeignKey(settings.AUTH_USER_MODEL, on_delete=models.PROTECT, related_name="deposits")
|
||||
utxo = models.OneToOneField(Utxo, on_delete=models.PROTECT, related_name="deposit")
|
||||
movement = models.OneToOneField(Movement, null=True, blank=True, on_delete=models.PROTECT, related_name="deposit")
|
||||
status = models.CharField(max_length=16, choices=Status.choices, default=Status.DETECTED)
|
||||
detected_at = models.DateTimeField(default=timezone.now)
|
||||
credited_at = models.DateTimeField(null=True, blank=True)
|
||||
|
||||
class Meta:
|
||||
constraints = [
|
||||
models.CheckConstraint(
|
||||
condition=Q(status__in=["detected", "credited", "orphaned"]), name="lottery_deposit_status_valid"
|
||||
),
|
||||
models.CheckConstraint(
|
||||
condition=~Q(status="credited") | (Q(movement__isnull=False) & Q(credited_at__isnull=False)),
|
||||
name="lottery_deposit_credited_has_movement",
|
||||
),
|
||||
]
|
||||
|
||||
def __str__(self) -> str:
|
||||
return f"Deposit {self.pk} ({self.status})"
|
||||
Reference in new issue
Block a user