sccp 0.1.1__py3-none-any.whl

sccp/__init__.py

@@ -0,0 +1,12 @@
+"""sccp -- a cryptocurrency whose proof of work is winning chess games.
+
+The package is import-light on purpose: importing :mod:`sccp` must not start
+engines, open databases or read configuration. Entry points (CLI, node, miner)
+call :func:`sccp.version.verify_chess_version` during startup so an unexpected
+``python-chess`` upgrade fails loudly instead of silently changing PGN parsing
+behaviour (docs/IMPLEMENTATION_PLAN.md section 3).
+"""
+
+from sccp.version import __version__
+
+__all__ = ["__version__"]

sccp/cli.py

@@ -0,0 +1,303 @@
+"""``sccp`` command line interface (docs/IMPLEMENTATION_PLAN.md section 5.13).
+
+M0 ships ``--version`` and the wallet basics: ``wallet new``, ``wallet address``,
+``wallet export-mnemonic`` and ``wallet import-mnemonic``. Every command is a thin
+wrapper over a library call so the same behaviour is testable in-process.
+
+Global options may be passed before or after the subcommand; an explicitly
+passed ``--network`` always wins over the global default of ``testnet``.
+"""
+
+from __future__ import annotations
+
+import json as jsonlib
+import os
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Annotated, NoReturn, TypeVar
+
+import typer
+
+from sccp import version as version_module
+from sccp.config import NetworkParams, get_network
+from sccp.crypto.wallet import (
+    DEFAULT_KDF,
+    KdfParams,
+    Wallet,
+    create_wallet,
+    export_mnemonic,
+    import_mnemonic,
+    read_header,
+    read_passphrase_file,
+)
+from sccp.errors import SccpError
+
+DEFAULT_NETWORK = "testnet"
+PASSPHRASE_ENV = "SCCP_WALLET_PASSPHRASE"
+
+T = TypeVar("T")
+
+app = typer.Typer(
+    add_completion=False,
+    no_args_is_help=True,
+    help="A cryptocurrency whose proof of work is winning chess games.",
+)
+wallet_app = typer.Typer(no_args_is_help=True, help="Create, inspect and back up wallets.")
+app.add_typer(wallet_app, name="wallet")
+
+
+@dataclass(frozen=True, slots=True)
+class GlobalOptions:
+    """Values supplied by the global options, before per-command overrides."""
+
+    network: str | None
+    data_dir: Path
+    passphrase_file: Path | None
+    json_output: bool
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(version_module.version_string())
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    network: Annotated[
+        str | None,
+        typer.Option("--network", help="Network id: mainnet, testnet or devnet."),
+    ] = None,
+    data_dir: Annotated[
+        Path,
+        typer.Option("--data-dir", help="Directory for chain and wallet data."),
+    ] = Path("./data"),
+    passphrase_file: Annotated[
+        Path | None,
+        typer.Option(
+            "--passphrase-file",
+            help="File holding the wallet passphrase (mode 0600, first line used).",
+        ),
+    ] = None,
+    log_level: Annotated[
+        str,
+        typer.Option("--log-level", help="Logging verbosity (info, debug, ...)."),
+    ] = "info",
+    json_output: Annotated[
+        bool,
+        typer.Option("--json", help="Print machine-readable JSON."),
+    ] = False,
+    version: Annotated[
+        bool,
+        typer.Option(
+            "--version",
+            "-V",
+            callback=_version_callback,
+            is_eager=True,
+            help="Show the package and protocol version, then exit.",
+        ),
+    ] = False,
+) -> None:
+    """Shared setup: verify the chess library, validate the network, store options."""
+    version_module.verify_chess_version()
+    if network is not None:
+        try:
+            get_network(network)
+        except SccpError as exc:
+            _fail(str(exc), code=2)
+    ctx.obj = GlobalOptions(
+        network=network,
+        data_dir=data_dir,
+        passphrase_file=passphrase_file,
+        json_output=json_output,
+    )
+
+
+def _options(ctx: typer.Context) -> GlobalOptions:
+    options = ctx.obj
+    if not isinstance(options, GlobalOptions):  # pragma: no cover - callback always sets it
+        raise typer.Exit(code=2)
+    return options
+
+
+def _fail(message: str, code: int = 1) -> NoReturn:
+    typer.secho(f"error: {message}", err=True)
+    raise typer.Exit(code=code)
+
+
+def _run(action: Callable[[], T]) -> T:
+    """Run a library call, turning typed errors into a clean CLI exit."""
+    try:
+        return action()
+    except SccpError as exc:
+        _fail(str(exc))
+
+
+def _resolve_network(ctx: typer.Context, network: str | None) -> NetworkParams:
+    options = _options(ctx)
+    return _run(lambda: get_network(network or options.network or DEFAULT_NETWORK))
+
+
+def _check_network(ctx: typer.Context, network: str | None, header_network: str) -> None:
+    """Refuse to operate on a keyfile belonging to a different network."""
+    explicit = network or _options(ctx).network
+    if explicit is None:
+        return
+    requested = _run(lambda: get_network(explicit))
+    if header_network != requested.network_id:
+        _fail(
+            f"keyfile belongs to network {header_network!r}, "
+            f"but --network {requested.network_id!r} was requested"
+        )
+
+
+def _passphrase(ctx: typer.Context, *, confirm: bool) -> str:
+    options = _options(ctx)
+    passphrase_file = options.passphrase_file
+    if passphrase_file is not None:
+        return _run(lambda: read_passphrase_file(passphrase_file))
+    from_env = os.environ.get(PASSPHRASE_ENV)
+    if from_env:
+        return from_env
+    return str(typer.prompt("Passphrase", hide_input=True, confirmation_prompt=confirm))
+
+
+def _echo_json(payload: object) -> None:
+    typer.echo(jsonlib.dumps(payload, sort_keys=True))
+
+
+def _emit_wallet(ctx: typer.Context, wallet: Wallet) -> None:
+    if _options(ctx).json_output:
+        _echo_json(
+            {
+                "address": wallet.address,
+                "network": wallet.network,
+                "public_key": wallet.public_key_hex,
+                "keyfile": str(wallet.path) if wallet.path is not None else None,
+            }
+        )
+        return
+    typer.echo(wallet.address)
+
+
+@wallet_app.command("new")
+def wallet_new(
+    ctx: typer.Context,
+    out: Annotated[Path, typer.Option("--out", help="Path of the keyfile to write.")],
+    network: Annotated[
+        str | None,
+        typer.Option("--network", help="Network the address is derived for."),
+    ] = None,
+    force: Annotated[
+        bool,
+        typer.Option("--force", help="Overwrite an existing keyfile."),
+    ] = False,
+    created_at: Annotated[
+        int | None,
+        typer.Option("--created-at", hidden=True, help="Fix created_at (tests)."),
+    ] = None,
+    kdf_n: Annotated[
+        int,
+        typer.Option("--kdf-n", hidden=True, help="scrypt N (tests only; default 2**15)."),
+    ] = DEFAULT_KDF.n,
+) -> None:
+    """Create an encrypted keyfile and print its address."""
+    params = _resolve_network(ctx, network)
+    passphrase = _passphrase(ctx, confirm=True)
+    wallet = _run(
+        lambda: create_wallet(
+            out,
+            params,
+            passphrase,
+            kdf=KdfParams(n=kdf_n),
+            created_at=created_at,
+            force=force,
+        )
+    )
+    _emit_wallet(ctx, wallet)
+
+
+@wallet_app.command("address")
+def wallet_address(
+    ctx: typer.Context,
+    key: Annotated[Path, typer.Option("--key", help="Keyfile to read.")],
+    network: Annotated[
+        str | None,
+        typer.Option("--network", help="Require the keyfile to belong to this network."),
+    ] = None,
+) -> None:
+    """Print the address stored in a keyfile; no passphrase is needed."""
+    header = _run(lambda: read_header(key))
+    _check_network(ctx, network, header.network)
+    if _options(ctx).json_output:
+        _echo_json(
+            {
+                "address": header.address,
+                "network": header.network,
+                "public_key": header.public_key,
+                "keyfile": str(key),
+            }
+        )
+        return
+    typer.echo(header.address)
+
+
+@wallet_app.command("export-mnemonic")
+def wallet_export_mnemonic(
+    ctx: typer.Context,
+    key: Annotated[Path, typer.Option("--key", help="Keyfile to decrypt.")],
+    network: Annotated[
+        str | None,
+        typer.Option("--network", help="Require the keyfile to belong to this network."),
+    ] = None,
+) -> None:
+    """Print the 24-word BIP-39 backup phrase for a keyfile."""
+    header = _run(lambda: read_header(key))
+    _check_network(ctx, network, header.network)
+    passphrase = _passphrase(ctx, confirm=False)
+    phrase = _run(lambda: export_mnemonic(key, passphrase))
+    if _options(ctx).json_output:
+        _echo_json({"mnemonic": phrase, "address": header.address, "network": header.network})
+        return
+    typer.echo(phrase)
+
+
+@wallet_app.command("import-mnemonic")
+def wallet_import_mnemonic(
+    ctx: typer.Context,
+    out: Annotated[Path, typer.Option("--out", help="Path of the keyfile to write.")],
+    network: Annotated[
+        str | None,
+        typer.Option("--network", help="Network the address is derived for."),
+    ] = None,
+    force: Annotated[
+        bool,
+        typer.Option("--force", help="Overwrite an existing keyfile."),
+    ] = False,
+    created_at: Annotated[
+        int | None,
+        typer.Option("--created-at", hidden=True, help="Fix created_at (tests)."),
+    ] = None,
+    kdf_n: Annotated[
+        int,
+        typer.Option("--kdf-n", hidden=True, help="scrypt N (tests only; default 2**15)."),
+    ] = DEFAULT_KDF.n,
+) -> None:
+    """Recreate a keyfile from a 24-word backup phrase."""
+    params = _resolve_network(ctx, network)
+    phrase = typer.prompt("Mnemonic (24 words)", hide_input=True)
+    passphrase = _passphrase(ctx, confirm=True)
+    wallet = _run(
+        lambda: import_mnemonic(
+            out,
+            phrase,
+            params,
+            passphrase,
+            kdf=KdfParams(n=kdf_n),
+            created_at=created_at,
+            force=force,
+        )
+    )
+    _emit_wallet(ctx, wallet)

sccp/config.py

@@ -0,0 +1,240 @@
+"""Immutable network parameters (docs/IMPLEMENTATION_PLAN.md section 5.1).
+
+Amounts are integer base units: ``1 coin = 100_000_000 units``. No floating
+point value is ever accepted by this module. ``NetworkParams`` validates its own
+invariants at construction, so an impossible network definition fails at import
+time rather than at block validation time.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Final, Self
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from sccp.errors import ConfigError, NetworkError
+
+UNITS_PER_COIN: Final = 100_000_000
+"""Base units per coin. All consensus amounts are integers of this unit."""
+
+MAX_PLIES_LIMIT: Final = 1000
+"""Hard upper bound for ``max_plies``; longer games are never consensus-valid."""
+
+
+def coins_to_units(coins: int) -> int:
+    """Convert whole coins to base units."""
+    if not isinstance(coins, int) or isinstance(coins, bool):
+        raise ConfigError("coin amounts must be integers")
+    return coins * UNITS_PER_COIN
+
+
+class QualityMode(StrEnum):
+    """Whether the quality policy is enforced for a network."""
+
+    OFF = "off"
+    SAMPLED = "sampled"
+
+
+class NetworkParams(BaseModel):
+    """One network's consensus constants. Frozen: instances are hashable and safe."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    # Identity
+    network_id: str = Field(min_length=1)
+    address_hrp: str = Field(min_length=1)
+    genesis_timestamp: int | None = None
+
+    # Epochs and matchmaking
+    epoch_length: int = Field(ge=1)
+    rounds_per_epoch: int = Field(ge=1)
+    availability_lead: int = Field(ge=2)
+    wins_required: int = Field(ge=1)
+    k_min: int = Field(ge=1)
+    k_max: int = Field(ge=1)
+    claim_window: int = Field(ge=1)
+    opponent_cooldown: int = Field(ge=0)
+
+    # Header seal and retargeting
+    seal_bits: int = Field(ge=0, le=32)
+    target_block_seconds: int = Field(ge=1)
+    retarget_interval: int = Field(ge=1)
+    retarget_enabled: bool = True
+
+    # Economics
+    subsidy: int = Field(gt=0)
+    halving_interval: int | None = Field(default=None, ge=1)
+    max_supply: int | None = Field(default=None, ge=1)
+    coinbase_maturity: int = Field(ge=0)
+    min_bond: int = Field(ge=0)
+    registration_epochs: int = Field(ge=1)
+    unbond_delay: int = Field(ge=0)
+    min_fee: int = Field(gt=0)
+    challenge_window: int = Field(ge=0)
+
+    # Chess rules
+    min_plies: int = Field(ge=1)
+    max_plies: int = Field(ge=1, le=MAX_PLIES_LIMIT)
+    nodes_per_move: int = Field(gt=0)
+    book_version: str = Field(min_length=1)
+
+    # Quality policy
+    quality_mode: QualityMode
+    quality_sample_rate: int = Field(ge=0, le=1000)
+
+    # Beacon
+    beacon_grace_blocks: int = Field(ge=0)
+    drand_chain: str | None = None
+    drand_period_seconds: int | None = Field(default=None, ge=1)
+    drand_round_offset: int | None = None
+
+    # Size caps
+    max_block_bytes: int = Field(gt=0)
+    max_pgn_bytes: int = Field(gt=0)
+    max_tx_bytes: int = Field(gt=0)
+
+    @property
+    def max_money(self) -> int | None:
+        """Supply cap in base units, or ``None`` when the network is uncapped."""
+        if self.max_supply is None:
+            return None
+        return self.max_supply * UNITS_PER_COIN
+
+    @model_validator(mode="after")
+    def _check_invariants(self) -> Self:
+        if self.retarget_interval % self.epoch_length != 0:
+            raise ValueError("retarget_interval must be a multiple of epoch_length")
+        if not self.k_min <= self.wins_required <= self.k_max:
+            raise ValueError("wins_required must satisfy k_min <= k <= k_max")
+        if self.min_plies > self.max_plies:
+            raise ValueError("min_plies must not exceed max_plies")
+        if self.max_block_bytes <= max(self.max_pgn_bytes, self.max_tx_bytes):
+            raise ValueError("max_block_bytes must exceed the PGN and tx caps")
+        if (self.max_supply is None) != (self.halving_interval is None):
+            raise ValueError("max_supply and halving_interval are set together or not at all")
+        drand_fields = (self.drand_period_seconds, self.drand_round_offset)
+        if self.drand_chain is None and any(field is not None for field in drand_fields):
+            raise ValueError("drand timing constants require drand_chain")
+        if self.drand_chain is not None and any(field is None for field in drand_fields):
+            raise ValueError("drand_chain requires drand_period_seconds and drand_round_offset")
+        if self.quality_mode is QualityMode.SAMPLED and self.quality_sample_rate == 0:
+            raise ValueError("quality_mode 'sampled' requires a non-zero quality_sample_rate")
+
+        max_money = self.max_money
+        if max_money is not None:
+            for name, amount in (
+                ("subsidy", self.subsidy),
+                ("min_bond", self.min_bond),
+                ("min_fee", self.min_fee),
+            ):
+                if amount > max_money:
+                    raise ValueError(f"{name} exceeds MAX_MONEY ({max_money})")
+        return self
+
+
+TESTNET: Final = NetworkParams(
+    network_id="testnet",
+    address_hrp="sccpt",
+    epoch_length=5,
+    rounds_per_epoch=3,
+    availability_lead=2,
+    wins_required=1,
+    k_min=1,
+    k_max=5,
+    claim_window=64,
+    opponent_cooldown=1,
+    seal_bits=0,
+    target_block_seconds=60,
+    retarget_interval=10,
+    subsidy=coins_to_units(50),
+    coinbase_maturity=20,
+    min_bond=coins_to_units(10),
+    registration_epochs=10,
+    unbond_delay=50,
+    min_fee=1_000,
+    challenge_window=30,
+    min_plies=20,
+    max_plies=300,
+    nodes_per_move=50_000,
+    book_version="dev-1",
+    quality_mode=QualityMode.OFF,
+    quality_sample_rate=0,
+    beacon_grace_blocks=2,
+    max_block_bytes=1_048_576,
+    max_pgn_bytes=262_144,
+    max_tx_bytes=65_536,
+)
+
+MAINNET: Final = NetworkParams(
+    network_id="mainnet",
+    address_hrp="sccp",
+    epoch_length=20,
+    rounds_per_epoch=5,
+    availability_lead=2,
+    wins_required=3,
+    k_min=1,
+    k_max=10,
+    claim_window=144,
+    opponent_cooldown=4,
+    seal_bits=16,
+    target_block_seconds=600,
+    retarget_interval=40,
+    subsidy=coins_to_units(50),
+    halving_interval=210_000,
+    max_supply=21_000_000,
+    coinbase_maturity=100,
+    min_bond=coins_to_units(500),
+    registration_epochs=30,
+    unbond_delay=1_000,
+    min_fee=1_000,
+    challenge_window=100,
+    min_plies=30,
+    max_plies=400,
+    nodes_per_move=250_000,
+    book_version="v1",
+    quality_mode=QualityMode.SAMPLED,
+    quality_sample_rate=50,
+    beacon_grace_blocks=6,
+    drand_chain="quicknet",
+    drand_period_seconds=3,
+    drand_round_offset=1,
+    max_block_bytes=1_048_576,
+    max_pgn_bytes=262_144,
+    max_tx_bytes=65_536,
+)
+
+DEVNET: Final = NetworkParams.model_validate(
+    {
+        **TESTNET.model_dump(),
+        "network_id": "devnet",
+        # Fully deterministic: one-block epochs, no retargeting, fixed genesis time.
+        "epoch_length": 1,
+        "target_block_seconds": 1,
+        "retarget_enabled": False,
+        "wins_required": 1,
+        "min_bond": 0,
+        "genesis_timestamp": 1_700_000_000,
+    }
+)
+"""In-process network for tests and CI: mock engines, zero seal difficulty."""
+
+NETWORKS: Final[dict[str, NetworkParams]] = {
+    params.network_id: params for params in (TESTNET, MAINNET, DEVNET)
+}
+
+
+def get_network(network: str | NetworkParams) -> NetworkParams:
+    """Resolve a network id (or pass a :class:`NetworkParams` through)."""
+    if isinstance(network, NetworkParams):
+        return network
+    try:
+        return NETWORKS[network]
+    except KeyError:
+        known = ", ".join(sorted(NETWORKS))
+        raise NetworkError(f"unknown network {network!r}; known networks: {known}") from None
+
+
+def network_ids() -> tuple[str, ...]:
+    """All known network ids, sorted."""
+    return tuple(sorted(NETWORKS))

sccp/crypto/__init__.py

@@ -0,0 +1,6 @@
+"""Key, address and wallet primitives.
+
+Import the submodules directly (``from sccp.crypto.keys import sign``); this
+package deliberately re-exports nothing so that a light-weight consumer such as
+the address encoder never pays for the wallet's key-derivation code.
+"""

sccp/crypto/address.py

@@ -0,0 +1,120 @@
+"""Bech32 addresses: ``sccp1...`` on mainnet, ``sccpt1...`` on testnet/devnet.
+
+An address is a 21-byte program -- one version byte (``0`` = Ed25519) plus the
+first 20 bytes of ``sha256("sccp/v1/address" + 0x00 + canonical_json({"network",
+"public_key"}))`` -- encoded with BIP-173 bech32. The segwit-style helpers in the
+``bech32`` package are not usable here: they hard-code witness program lengths
+and reject the 21-byte program this protocol needs, so we use the primitives
+``bech32_encode``/``bech32_decode``/``convertbits`` directly
+(docs/IMPLEMENTATION_PLAN.md section 5.3).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Final
+
+import bech32
+
+from sccp.config import NetworkParams, get_network
+from sccp.crypto.keys import PUBLIC_KEY_SIZE
+from sccp.errors import AddressError, KeyEncodingError
+from sccp.serialization import Domain, domain_hash
+
+ADDRESS_VERSION: Final = 0
+"""Program version byte for Ed25519 keys."""
+
+HASH_SIZE: Final = 20
+"""Address hash length in bytes."""
+
+PROGRAM_SIZE: Final = 1 + HASH_SIZE
+"""Version byte plus hash."""
+
+MAX_ADDRESS_LENGTH: Final = 90
+"""BIP-173 limit, in characters."""
+
+
+@dataclass(frozen=True, slots=True)
+class DecodedAddress:
+    """A syntactically valid bech32 address, independent of network choice."""
+
+    hrp: str
+    version: int
+    payload: bytes
+
+    @property
+    def program(self) -> bytes:
+        """The 21-byte ``version || hash`` program."""
+        return bytes([self.version]) + self.payload
+
+    @property
+    def hash_hex(self) -> str:
+        return self.payload.hex()
+
+
+def address_hash(network_id: str, public_key: bytes | bytearray) -> bytes:
+    """The 20-byte address hash for ``public_key`` on ``network_id``."""
+    raw = bytes(public_key)
+    if len(raw) != PUBLIC_KEY_SIZE:
+        raise KeyEncodingError(
+            f"Ed25519 public key must be {PUBLIC_KEY_SIZE} bytes, got {len(raw)}"
+        )
+    digest = domain_hash(Domain.ADDRESS, {"network": network_id, "public_key": raw.hex()})
+    return digest[:HASH_SIZE]
+
+
+def address_program(network_id: str, public_key: bytes | bytearray) -> bytes:
+    """The 21-byte program committed to by the bech32 string."""
+    return bytes([ADDRESS_VERSION]) + address_hash(network_id, public_key)
+
+
+def encode_address(public_key: bytes | bytearray, network: str | NetworkParams) -> str:
+    """Encode ``public_key`` as a lowercase bech32 address on ``network``."""
+    params = get_network(network)
+    program = address_program(params.network_id, public_key)
+    words = bech32.convertbits(program, 8, 5, True)
+    if words is None:  # pragma: no cover - impossible for 21 bytes
+        raise AddressError("cannot convert address program to 5-bit words")
+    return bech32.bech32_encode(params.address_hrp, words)
+
+
+def _decode_words(address: str) -> tuple[str, list[int]]:
+    if not isinstance(address, str):
+        raise AddressError(f"address must be a string, got {type(address).__name__}")
+    if not address:
+        raise AddressError("address is empty")
+    if len(address) > MAX_ADDRESS_LENGTH:
+        raise AddressError(f"address exceeds {MAX_ADDRESS_LENGTH} characters")
+    if address.lower() != address and address.upper() != address:
+        raise AddressError("address mixes upper and lower case")
+    hrp, words = bech32.bech32_decode(address)
+    if hrp is None or words is None:
+        raise AddressError(f"invalid bech32 address: {address!r}")
+    return hrp, words
+
+
+def decode_address(address: str) -> DecodedAddress:
+    """Parse any well-formed sccp address, regardless of network."""
+    hrp, words = _decode_words(address)
+    program = bech32.convertbits(words, 5, 8, False)
+    if program is None or len(program) != PROGRAM_SIZE:
+        raise AddressError(f"address program must be {PROGRAM_SIZE} bytes")
+    version = program[0]
+    if version != ADDRESS_VERSION:
+        raise AddressError(f"unsupported address version {version}")
+    return DecodedAddress(hrp=hrp, version=version, payload=bytes(program[1:]))
+
+
+def validate_address(address: str, network: str | NetworkParams) -> bool:
+    """Return whether ``address`` parses and belongs to ``network``."""
+    params = get_network(network)
+    try:
+        decoded = decode_address(address)
+    except AddressError:
+        return False
+    return decoded.hrp == params.address_hrp
+
+
+def address_for_public_key(public_key: bytes | bytearray, network: str | NetworkParams) -> str:
+    """Alias for :func:`encode_address`, spelled for readability at call sites."""
+    return encode_address(public_key, network)