pythsol 0.1.0__py3-none-any.whl

pythsol/cli/template_programs/vault.py

@@ -0,0 +1,67 @@
+"""Vault: a PDA that holds lamports for one authority.
+
+``deposit`` moves lamports in with ``system_transfer``. ``close`` checks the
+authority, then returns every lamport on the account. The PDA seed is the
+literal ``vault`` (one seed, plus the bump).
+"""
+
+from pythsol import (
+    CloseTo,
+    HasOne,
+    Init,
+    Mut,
+    ProgramError,
+    Pubkey,
+    Seeds,
+    Signer,
+    account,
+    error,
+    instruction,
+    require,
+    system_transfer,
+    u8,
+    u64,
+)
+
+
+@account
+class Vault:
+    authority: Pubkey
+    balance: u64
+    bump: u8
+
+
+@error
+class VaultError(ProgramError):
+    """Errors returned by this program (6000 + index)."""
+
+    Unauthorized = 100
+
+
+@instruction
+def initialize(
+    authority: Signer,
+    vault: Seeds[Init[Vault], "vault"],  # type: ignore[name-defined]  # noqa: F821
+    bump: u8,
+) -> None:
+    vault.authority = authority.key
+    vault.balance = 0
+    vault.bump = bump
+
+
+@instruction
+def deposit(
+    authority: Signer,
+    vault: HasOne[Mut[Vault], "authority"],  # type: ignore[name-defined]  # noqa: F821
+    amount: u64,
+) -> None:
+    system_transfer(authority, vault, amount)
+    vault.balance += amount
+
+
+@instruction
+def close(
+    authority: Signer,
+    vault: CloseTo[Mut[Vault], authority],  # type: ignore[name-defined]  # noqa: F821
+) -> None:
+    require(vault.authority == authority.key, VaultError.Unauthorized)

pythsol/cli/templates.py

@@ -0,0 +1,192 @@
+"""Project files written by `pythsol init`.
+
+Program sources live in :mod:`pythsol.cli.template_programs` so a scaffold
+does not depend on the ``examples/`` tree being installed.
+"""
+
+from __future__ import annotations
+
+from importlib.resources import files
+
+__all__ = ["TEMPLATES", "program_source", "program_test_source", "project_files"]
+
+TEMPLATES: tuple[str, ...] = ("counter", "ledger", "vault", "escrow", "multisig", "poll")
+
+_PYSOL = """\
+[project]
+name = "{name}"
+python = ">=3.11"
+
+[[programs]]
+name = "{name}"
+entry = "programs/{name}.py"
+
+[build]
+sbpf = "v0"
+heap_kib = 32
+out_dir = "target/pythsol"
+"""
+
+_PYPROJECT = """\
+[project]
+name = "{name}"
+version = "0.1.0"
+description = "Solana program written with PythSol"
+requires-python = ">=3.11"
+dependencies = ["pythsol"]
+"""
+
+_README = """\
+# {name}
+
+PythSol program. From this directory:
+
+```bash
+pythsol check programs/{name}.py
+pythsol build programs/{name}.py
+pythsol idl programs/{name}.py
+```
+
+`pythsol build` writes a native SBF `.so`, an Anchor-style IDL, and
+`{name}_client.py` (solders instruction builders). `pythsol test` builds
+again (a cache hit skips clang) and runs `tests/` on LiteSVM.
+"""
+
+
+def program_source(template: str) -> str:
+    """Return the embedded program source for ``template``."""
+    resource = files("pythsol.cli.template_programs").joinpath(f"{template}.py")
+    return resource.read_text(encoding="utf-8")
+
+
+_COUNTER_TEST = """\
+def test_increment(program, payer):
+    opened = program.initialize(authority=payer)
+    counter = opened.account("counter")
+    program.increment(authority=payer, counter=counter, by=5)
+    state = program.fetch("Counter", counter)
+    assert state["count"] == 5
+
+
+def test_unauthorized(program, payer):
+    opened = program.initialize(authority=payer)
+    counter = opened.account("counter")
+    stranger = program.keypair()
+    with program.expect_error("Unauthorized"):
+        program.increment(authority=stranger, counter=counter, by=1)
+"""
+
+_LEDGER_TEST = """\
+def test_deposit(program, payer):
+    opened = program.initialize(authority=payer)
+    ledger = opened.account("ledger")
+    program.deposit(authority=payer, ledger=ledger, slot=1, amount=5)
+    state = program.fetch("Ledger", ledger)
+    assert state["total"] == 5
+"""
+
+_VAULT_TEST = """\
+def test_deposit_and_close(program, payer):
+    opened = program.initialize(authority=payer)
+    vault = opened.account("vault")
+    program.deposit(authority=payer, vault=vault, amount=1000)
+    state = program.fetch("Vault", vault)
+    assert state["balance"] == 1000
+    program.close(authority=payer, vault=vault)
+"""
+
+_ESCROW_TEST = """\
+def test_make_and_take(program, payer):
+    taker = program.keypair()
+    opened = program.make(maker=payer, taker=taker, amount=1000)
+    escrow = opened.account("escrow")
+    program.take(taker=taker, maker=payer, escrow=escrow, price=400)
+"""
+
+_MULTISIG_TEST = """\
+def test_two_of_three(program, payer):
+    first = program.keypair()
+    second = program.keypair()
+    third = program.keypair()
+    dest = program.keypair()
+    opened = program.initialize(
+        authority=payer,
+        first=first.pubkey(),
+        second=second.pubkey(),
+        third=third.pubkey(),
+        threshold=2,
+    )
+    treasury = opened.account("treasury")
+    program.fund(donor=payer, treasury=treasury, amount=1000)
+    program.approve(owner=first, treasury=treasury, slot=0)
+    program.approve(owner=second, treasury=treasury, slot=1)
+    program.release(owner=second, treasury=treasury, dest=dest, slot=1, amount=400)
+    assert program.fetch("Treasury", treasury)["paid"] == 400
+
+
+def test_one_approval_is_not_enough(program, payer):
+    first = program.keypair()
+    second = program.keypair()
+    third = program.keypair()
+    dest = program.keypair()
+    opened = program.initialize(
+        authority=payer,
+        first=first.pubkey(),
+        second=second.pubkey(),
+        third=third.pubkey(),
+        threshold=2,
+    )
+    treasury = opened.account("treasury")
+    program.fund(donor=payer, treasury=treasury, amount=1000)
+    program.approve(owner=first, treasury=treasury, slot=0)
+    with program.expect_error("NotApproved"):
+        program.release(owner=second, treasury=treasury, dest=dest, slot=1, amount=400)
+"""
+
+_POLL_TEST = """\
+def test_one_vote_per_key(program, payer):
+    voters = [program.keypair() for _ in range(4)]
+    opened = program.initialize(
+        authority=payer,
+        first=voters[0].pubkey(),
+        second=voters[1].pubkey(),
+        third=voters[2].pubkey(),
+        fourth=voters[3].pubkey(),
+    )
+    poll = opened.account("poll")
+    program.vote(voter=voters[0], poll=poll, slot=0, choice=True)
+    program.vote(voter=voters[3], poll=poll, slot=3, choice=False)
+    state = program.fetch("Poll", poll)
+    assert state["yes"] == 1
+    assert state["no"] == 1
+    with program.expect_error("AlreadyVoted"):
+        program.vote(voter=voters[0], poll=poll, slot=0, choice=True)
+"""
+
+_TEMPLATE_TESTS = {
+    "counter": _COUNTER_TEST,
+    "ledger": _LEDGER_TEST,
+    "vault": _VAULT_TEST,
+    "escrow": _ESCROW_TEST,
+    "multisig": _MULTISIG_TEST,
+    "poll": _POLL_TEST,
+}
+
+
+def program_test_source(template: str) -> str:
+    """Pytest source for ``template``. It uses plugin fixtures only."""
+    try:
+        return _TEMPLATE_TESTS[template]
+    except KeyError as exc:
+        raise ValueError(f"unknown template {template}") from exc
+
+
+def project_files(name: str, template: str) -> dict[str, str]:
+    """Relative path → file text for a new project."""
+    return {
+        "pysol.toml": _PYSOL.format(name=name),
+        "pyproject.toml": _PYPROJECT.format(name=name),
+        "README.md": _README.format(name=name),
+        f"programs/{name}.py": program_source(template),
+        "tests/test_program.py": program_test_source(template),
+    }

pythsol/client/__init__.py

@@ -0,0 +1,5 @@
+"""Python client generation (solders instruction builders and account decoders)."""
+
+from pythsol.client.gen import render_client
+
+__all__ = ["render_client"]

pythsol/client/from_idl.py

@@ -0,0 +1,356 @@
+"""Render a solders client from an Anchor-legacy IDL document.
+
+``pythsol build`` still uses :func:`pythsol.client.gen.render_client`, which
+sees the program model. This path is for ``pythsol client program.json``,
+where the only input is the IDL. CPI programs to append live under
+``metadata.pythsol.cpi`` (written by :func:`pythsol.compiler.idl.build_idl`).
+The generated module imports solders, not the compiler.
+"""
+
+from __future__ import annotations
+
+import keyword
+from typing import Any
+
+__all__ = ["render_client_from_idl"]
+
+_SYSTEM = "11111111111111111111111111111111"
+_TOKEN = "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"
+_TOKEN_2022 = "TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb"
+_ATA = "ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL"
+
+_FMT = {
+    "u8": "<B",
+    "u16": "<H",
+    "u32": "<I",
+    "u64": "<Q",
+    "i8": "<b",
+    "i16": "<h",
+    "i32": "<i",
+    "i64": "<q",
+    "bool": "<B",
+}
+
+_WIDTH = {
+    "u8": 1,
+    "u16": 2,
+    "u32": 4,
+    "u64": 8,
+    "u128": 16,
+    "i8": 1,
+    "i16": 2,
+    "i32": 4,
+    "i64": 8,
+    "i128": 16,
+    "bool": 1,
+    "publicKey": 32,
+}
+
+_EMPTY_CPI = {
+    "ata": False,
+    "pays": False,
+    "system": False,
+    "token": False,
+    "token2022": False,
+}
+
+
+class IdlClientError(Exception):
+    """The IDL uses a type this renderer does not pack."""
+
+
+def render_client_from_idl(idl: dict[str, Any], *, address: str | None = None) -> str:
+    """Return ``{name}_client.py`` source for ``idl``."""
+    name = str(idl.get("name") or "program")
+    flags = [_cpi(idl, str(item.get("name") or "")) for item in idl.get("instructions") or []]
+    needs_token = any(item["token"] or item["ata"] for item in flags)
+    needs_token2022 = any(item["token2022"] for item in flags)
+    needs_ata = any(item["ata"] for item in flags)
+    lines = [
+        '"""Generated by PythSol from an IDL. Do not edit.',
+        "",
+        f"Program `{name}`.",
+        "Build transactions with solders. This module does not import the compiler.",
+        '"""',
+        "",
+        "from __future__ import annotations",
+        "",
+        "import struct",
+        "",
+        "from solders.instruction import AccountMeta, Instruction",
+        "from solders.pubkey import Pubkey",
+        "",
+        f"PROGRAM_NAME = {name!r}",
+    ]
+    if address:
+        lines.append(f"PROGRAM_ID = {address!r}")
+    lines.append(f'_SYSTEM_PROGRAM = Pubkey.from_string("{_SYSTEM}")')
+    if needs_token:
+        lines.append(f'_TOKEN_PROGRAM = Pubkey.from_string("{_TOKEN}")')
+    if needs_token2022:
+        lines.append(f'_TOKEN_2022_PROGRAM = Pubkey.from_string("{_TOKEN_2022}")')
+    if needs_ata:
+        lines.append(f'_ATA_PROGRAM = Pubkey.from_string("{_ATA}")')
+    lines.append("")
+    types = _types(idl)
+    lines.extend(_enum_constants(types))
+    for instr in idl.get("instructions") or []:
+        if isinstance(instr, dict):
+            lines.extend(_instruction(instr, _cpi(idl, str(instr.get("name") or "")), types))
+            lines.append("")
+    for account in idl.get("accounts") or []:
+        if isinstance(account, dict):
+            lines.extend(_decode_account(account, types))
+            lines.append("")
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def _types(idl: dict[str, Any]) -> dict[str, dict[str, Any]]:
+    found: dict[str, dict[str, Any]] = {}
+    for item in idl.get("types") or []:
+        if isinstance(item, dict) and isinstance(item.get("name"), str):
+            found[item["name"]] = item
+    return found
+
+
+def _cpi(idl: dict[str, Any], name: str) -> dict[str, bool]:
+    metadata = idl.get("metadata")
+    if not isinstance(metadata, dict):
+        return dict(_EMPTY_CPI)
+    pythsol = metadata.get("pythsol")
+    if not isinstance(pythsol, dict):
+        return dict(_EMPTY_CPI)
+    table = pythsol.get("cpi")
+    if not isinstance(table, dict):
+        return dict(_EMPTY_CPI)
+    raw = table.get(name)
+    if not isinstance(raw, dict):
+        return dict(_EMPTY_CPI)
+    return {key: bool(raw.get(key)) for key in _EMPTY_CPI}
+
+
+def _enum_constants(types: dict[str, dict[str, Any]]) -> list[str]:
+    lines: list[str] = []
+    for name, info in types.items():
+        body = info.get("type")
+        if not isinstance(body, dict) or body.get("kind") != "enum":
+            continue
+        variants = body.get("variants")
+        if not isinstance(variants, list):
+            continue
+        if not lines:
+            lines.append("# Unit enum tags (declaration index, one byte).")
+        for index, variant in enumerate(variants):
+            if isinstance(variant, dict) and isinstance(variant.get("name"), str):
+                const = f"{name.upper()}_{variant['name'].upper()}"
+                lines.append(f"{const} = {index}  # {name}.{variant['name']}")
+    if lines:
+        lines.append("")
+    return lines
+
+
+def _fn_name(name: str, used: set[str]) -> str:
+    candidate = name + "_" if keyword.iskeyword(name) else name
+    while candidate in used:
+        candidate += "_"
+    used.add(candidate)
+    return candidate
+
+
+def _py_type(ty: Any, types: dict[str, dict[str, Any]]) -> str:
+    if ty == "publicKey":
+        return "Pubkey"
+    if ty == "bool":
+        return "bool"
+    if isinstance(ty, str):
+        return "int"
+    if isinstance(ty, dict) and ty.get("defined"):
+        info = types.get(str(ty["defined"]))
+        body = info.get("type") if isinstance(info, dict) else None
+        if isinstance(body, dict) and body.get("kind") == "enum":
+            return "int"
+        return "object"
+    return "object"
+
+
+def _pack_expr(ty: Any, name: str, types: dict[str, dict[str, Any]]) -> str:
+    if ty == "publicKey":
+        return f"bytes({name})"
+    if ty == "bool":
+        return f'struct.pack("<B", 1 if {name} else 0)'
+    if ty == "u128":
+        return f'{name}.to_bytes(16, "little")'
+    if ty == "i128":
+        return f'{name}.to_bytes(16, "little", signed=True)'
+    if isinstance(ty, str) and ty in _FMT:
+        return f'struct.pack("{_FMT[ty]}", {name})'
+    if isinstance(ty, dict) and isinstance(ty.get("defined"), str):
+        info = types.get(ty["defined"])
+        body = info.get("type") if isinstance(info, dict) else None
+        if isinstance(body, dict) and body.get("kind") == "enum":
+            return f'struct.pack("<B", {name})'
+    raise IdlClientError(f"cannot pack IDL type {ty!r}")
+
+
+def _instruction(
+    instr: dict[str, Any],
+    cpi: dict[str, bool],
+    types: dict[str, dict[str, Any]],
+) -> list[str]:
+    raw_name = str(instr.get("name") or "ix")
+    disc = instr.get("discriminator")
+    if not isinstance(disc, list) or len(disc) != 8:
+        raise IdlClientError(f"instruction `{raw_name}` needs an 8-byte discriminator")
+    const = f"_DISC_{raw_name.upper()}"
+    inner = ", ".join(str(int(byte) & 0xFF) for byte in disc)
+    used = {"program_id"}
+    params = ["program_id: Pubkey"]
+    account_lines: list[str] = []
+    raw_accounts = instr.get("accounts")
+    accounts = raw_accounts if isinstance(raw_accounts, list) else []
+    for account in accounts:
+        if not isinstance(account, dict):
+            continue
+        arg = _fn_name(str(account.get("name") or "account"), used)
+        params.append(f"{arg}: Pubkey")
+        signer = bool(account.get("isSigner"))
+        writable = bool(account.get("isMut")) or (signer and cpi["pays"])
+        account_lines.append(
+            f"        AccountMeta({arg}, is_signer={signer}, is_writable={writable}),"
+        )
+    data_exprs = [const]
+    raw_args = instr.get("args")
+    args = raw_args if isinstance(raw_args, list) else []
+    for arg in args:
+        if not isinstance(arg, dict):
+            continue
+        arg_name = _fn_name(str(arg.get("name") or "arg"), used)
+        params.append(f"{arg_name}: {_py_type(arg.get('type'), types)}")
+        data_exprs.append(_pack_expr(arg.get("type"), arg_name, types))
+    if cpi["system"]:
+        account_lines.append(
+            "        AccountMeta(_SYSTEM_PROGRAM, is_signer=False, is_writable=False),"
+        )
+    if cpi["token"] or cpi["ata"]:
+        account_lines.append(
+            "        AccountMeta(_TOKEN_PROGRAM, is_signer=False, is_writable=False),"
+        )
+    if cpi["token2022"]:
+        account_lines.append(
+            "        AccountMeta(_TOKEN_2022_PROGRAM, is_signer=False, is_writable=False),"
+        )
+    if cpi["ata"]:
+        account_lines.append(
+            "        AccountMeta(_ATA_PROGRAM, is_signer=False, is_writable=False),"
+        )
+    header = f"def {raw_name}(" + ", ".join(params) + ") -> Instruction:"
+    lines = [f"{const} = bytes(({inner}))", ""]
+    if len(header) <= 100 and "\n" not in header:
+        lines.append(header)
+    else:
+        lines.append(f"def {raw_name}(")
+        for param in params:
+            lines.append(f"    {param},")
+        lines.append(") -> Instruction:")
+    lines.append(f'    """Build the `{raw_name}` instruction."""')
+    if len(data_exprs) == 1:
+        lines.append(f"    data = {const}")
+    else:
+        lines.append("    data = b''.join((")
+        for expr in data_exprs:
+            lines.append(f"        {expr},")
+        lines.append("    ))")
+    lines.append("    accounts = [")
+    lines.extend(account_lines)
+    lines.append("    ]")
+    lines.append("    return Instruction(program_id=program_id, data=data, accounts=accounts)")
+    return lines
+
+
+def _simple_width(ty: Any, types: dict[str, dict[str, Any]]) -> int | None:
+    if isinstance(ty, str):
+        return _WIDTH.get(ty)
+    if isinstance(ty, dict) and isinstance(ty.get("defined"), str):
+        info = types.get(ty["defined"])
+        body = info.get("type") if isinstance(info, dict) else None
+        if isinstance(body, dict) and body.get("kind") == "enum":
+            return 1
+    if isinstance(ty, dict) and isinstance(ty.get("array"), list) and len(ty["array"]) == 2:
+        inner, count = ty["array"]
+        width = _simple_width(inner, types)
+        if width is None or not isinstance(count, int):
+            return None
+        return width * count
+    return None
+
+
+def _read_simple(name: str, ty: Any, offset: int, types: dict[str, dict[str, Any]]) -> str:
+    if ty == "publicKey":
+        return f"    {name} = Pubkey.from_bytes(data[{offset}:{offset + 32}])"
+    if ty == "bool":
+        return f"    {name} = bool(data[{offset}])"
+    if ty == "u128":
+        return f'    {name} = int.from_bytes(data[{offset}:{offset + 16}], "little")'
+    if ty == "i128":
+        return f'    {name} = int.from_bytes(data[{offset}:{offset + 16}], "little", signed=True)'
+    if isinstance(ty, str) and ty in _FMT:
+        if ty == "u8":
+            return f"    {name} = data[{offset}]"
+        return f'    ({name},) = struct.unpack_from("{_FMT[ty]}", data, {offset})'
+    if isinstance(ty, dict) and isinstance(ty.get("defined"), str):
+        return f"    {name} = data[{offset}]"
+    width = _simple_width(ty, types)
+    if width is None:
+        raise IdlClientError(f"cannot read IDL type {ty!r}")
+    return f"    {name} = data[{offset}:{offset + width}]"
+
+
+def _decode_account(account: dict[str, Any], types: dict[str, dict[str, Any]]) -> list[str]:
+    name = str(account.get("name") or "Account")
+    fn = "decode_" + _snake(name)
+    body = account.get("type") if isinstance(account.get("type"), dict) else {}
+    fields = body.get("fields") if isinstance(body, dict) else None
+    if not isinstance(fields, list):
+        fields = []
+    offset = 8
+    reads: list[str] = []
+    simple = True
+    for field in fields:
+        if not isinstance(field, dict):
+            simple = False
+            break
+        width = _simple_width(field.get("type"), types)
+        if width is None:
+            simple = False
+            break
+        field_name = str(field.get("name") or "field")
+        if isinstance(field.get("type"), dict) and isinstance(field["type"].get("array"), list):
+            simple = False
+            break
+        reads.append(_read_simple(field_name, field.get("type"), offset, types))
+        offset += width
+    lines = [
+        f"def {fn}(data: bytes) -> dict[str, object]:",
+        f'    """Decode a `{name}` account (discriminator plus fields)."""',
+    ]
+    if not simple:
+        lines.append(f'    raise NotImplementedError("decode `{name}` from the program source")')
+        return lines
+    lines.append(f"    if len(data) < {offset}:")
+    lines.append(f'        raise ValueError("{name} account is shorter than {offset} bytes")')
+    lines.extend(reads)
+    lines.append("    return {")
+    for field in fields:
+        if isinstance(field, dict):
+            lines.append(f"        {str(field.get('name') or 'field')!r}: {field.get('name')},")
+    lines.append("    }")
+    return lines
+
+
+def _snake(name: str) -> str:
+    out: list[str] = []
+    for char in name:
+        if char.isupper() and out and out[-1] != "_":
+            out.append("_")
+        out.append(char.lower())
+    return "".join(out)