pythsol 0.1.0__py3-none-any.whl

pythsol/cli/commands/wallet.py

@@ -0,0 +1,128 @@
+"""`pythsol wallet` — new keypair, address, and balance.
+
+The keypair file is the Solana JSON array (64 bytes). It is written mode
+``0600``. The secret is not printed unless ``--show-secret`` is set.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+import click
+
+from pythsol.cli.cluster import resolve_url
+from pythsol.cli.rpc import RpcError, post_json
+from pythsol.compiler.toolchain import default_solana_keypair
+
+
+def restrict_private_file(path: Path) -> None:
+    """Owner read/write only. On Windows, chmod is the best the CRT offers."""
+    os.chmod(path, 0o600)
+
+
+def _keypair_type() -> Any:
+    try:
+        from solders.keypair import Keypair
+    except ImportError:
+        click.echo("error: solders is required. pip install 'pythsol[test]'", err=True)
+        sys.exit(1)
+    return Keypair
+
+
+def _load(path: Path) -> Any:
+    return _keypair_type().from_json(path.read_text(encoding="utf-8"))
+
+
+def _lamports(body: dict[str, object]) -> int:
+    result = body.get("result")
+    if isinstance(result, dict) and "value" in result:
+        return int(result["value"])
+    if isinstance(result, int):
+        return result
+    raise RpcError("balance response had no value")
+
+
+@click.group(name="wallet")
+def wallet() -> None:
+    """Create a keypair, print its address, or read a balance."""
+
+
+@wallet.command("new")
+@click.option(
+    "--outfile",
+    required=True,
+    type=click.Path(dir_okay=False, path_type=Path),
+    help="Where to write the keypair JSON.",
+)
+@click.option("--force", is_flag=True, help="Overwrite an existing file.")
+@click.option("--show-secret", is_flag=True, help="Print the keypair JSON. Off by default.")
+def wallet_new(outfile: Path, force: bool, show_secret: bool) -> None:
+    """Write a new keypair file."""
+    if outfile.exists() and not force:
+        click.echo(f"error: {outfile} already exists (pass --force to overwrite)", err=True)
+        sys.exit(1)
+    outfile.parent.mkdir(parents=True, exist_ok=True)
+    keypair = _keypair_type()()
+    text = keypair.to_json()
+    if not text.endswith("\n"):
+        text += "\n"
+    outfile.write_text(text, encoding="utf-8", newline="\n")
+    restrict_private_file(outfile)
+    click.echo(f"wrote {outfile}")
+    click.echo(str(keypair.pubkey()))
+    if show_secret:
+        click.echo(text, nl=False)
+    sys.exit(0)
+
+
+@wallet.command("address")
+@click.option(
+    "--keypair",
+    "keypair_path",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    default=None,
+)
+@click.option("--show-secret", is_flag=True, help="Print the keypair JSON. Off by default.")
+def wallet_address(keypair_path: Path | None, show_secret: bool) -> None:
+    """Print the public key. The secret stays in the file."""
+    path = keypair_path or default_solana_keypair()
+    if not path.is_file():
+        click.echo(f"error: keypair not found at {path}", err=True)
+        sys.exit(1)
+    keypair = _load(path)
+    click.echo(str(keypair.pubkey()))
+    if show_secret:
+        click.echo(keypair.to_json())
+    sys.exit(0)
+
+
+@wallet.command("balance")
+@click.option("--url", default=None, help="Cluster name or RPC URL. Default: devnet.")
+@click.option("--pubkey", default=None, help="Base58 address. Default: the local keypair.")
+@click.option(
+    "--keypair",
+    "keypair_path",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    default=None,
+)
+def wallet_balance(url: str | None, pubkey: str | None, keypair_path: Path | None) -> None:
+    """Print the SOL balance of a public key."""
+    if pubkey is None:
+        path = keypair_path or default_solana_keypair()
+        if not path.is_file():
+            click.echo(f"error: keypair not found at {path}", err=True)
+            sys.exit(1)
+        pubkey = str(_load(path).pubkey())
+    cluster = resolve_url(url)
+    try:
+        body = post_json(cluster, "getBalance", [pubkey])
+        lamports = _lamports(body)
+    except RpcError as exc:
+        click.echo(f"error: {exc}", err=True)
+        sys.exit(1)
+    sol = lamports / 1_000_000_000
+    click.echo(f"{sol:.4f} SOL ({lamports} lamports)")
+    sys.exit(0)

pythsol/cli/config.py

@@ -0,0 +1,84 @@
+"""Read ``pysol.toml`` project files."""
+
+from __future__ import annotations
+
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+__all__ = ["ConfigError", "ProgramEntry", "ProjectConfig", "find_config", "load_config"]
+
+
+class ConfigError(Exception):
+    """``pysol.toml`` is missing a required field or has the wrong shape."""
+
+
+@dataclass(frozen=True)
+class ProgramEntry:
+    """One ``[[programs]]`` row."""
+
+    name: str
+    entry: Path
+
+
+@dataclass(frozen=True)
+class ProjectConfig:
+    """The fields `pythsol test` and `pythsol build` read from a project."""
+
+    path: Path
+    name: str
+    programs: tuple[ProgramEntry, ...]
+    out_dir: Path
+    cluster: str
+
+
+def find_config(start: Path) -> Path | None:
+    """Walk from ``start`` toward the filesystem root looking for ``pysol.toml``."""
+    current = start.resolve()
+    if current.is_file():
+        current = current.parent
+    for directory in [current, *current.parents]:
+        candidate = directory / "pysol.toml"
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def load_config(path: Path) -> ProjectConfig:
+    """Parse ``path``. Raises :class:`ConfigError` on a bad shape."""
+    raw: dict[str, Any] = tomllib.loads(path.read_text(encoding="utf-8"))
+    project = raw.get("project")
+    build = raw.get("build")
+    cluster = raw.get("cluster")
+    programs_raw = raw.get("programs")
+    if not isinstance(programs_raw, list) or not programs_raw:
+        raise ConfigError("pysol.toml needs at least one [[programs]] entry")
+    root = path.parent
+    programs: list[ProgramEntry] = []
+    for item in programs_raw:
+        if not isinstance(item, dict):
+            raise ConfigError("[[programs]] entries must be tables")
+        name = item.get("name")
+        entry = item.get("entry")
+        if not isinstance(name, str) or not name:
+            raise ConfigError("a program needs a name")
+        if not isinstance(entry, str) or not entry:
+            raise ConfigError(f"program `{name}` needs an entry path")
+        programs.append(ProgramEntry(name, (root / entry).resolve()))
+    out_raw = "target/pythsol"
+    if isinstance(build, dict) and isinstance(build.get("out_dir"), str):
+        out_raw = build["out_dir"]
+    default_cluster = "devnet"
+    if isinstance(cluster, dict) and isinstance(cluster.get("default"), str):
+        default_cluster = cluster["default"]
+    project_name = root.name
+    if isinstance(project, dict) and isinstance(project.get("name"), str):
+        project_name = project["name"]
+    return ProjectConfig(
+        path=path,
+        name=project_name,
+        programs=tuple(programs),
+        out_dir=(root / out_raw).resolve(),
+        cluster=default_cluster,
+    )

pythsol/cli/main.py

@@ -0,0 +1,72 @@
+"""CLI entry point (`pythsol`, aliased as the draft `pysol`)."""
+
+from __future__ import annotations
+
+import os
+import sys
+
+import click
+
+from pythsol import __version__
+from pythsol.cli.commands.build import build
+from pythsol.cli.commands.check import check
+from pythsol.cli.commands.client_cmd import client_cmd, cpi_cmd
+from pythsol.cli.commands.deploy import deploy
+from pythsol.cli.commands.docs_cmd import docs
+from pythsol.cli.commands.doctor import doctor
+from pythsol.cli.commands.emit_c import emit_c
+from pythsol.cli.commands.faucet import faucet
+from pythsol.cli.commands.idl_cmd import idl
+from pythsol.cli.commands.idl_publish import idl_publish
+from pythsol.cli.commands.init import init
+from pythsol.cli.commands.port_cmd import port_cmd
+from pythsol.cli.commands.profile import profile
+from pythsol.cli.commands.serve import serve
+from pythsol.cli.commands.test_cmd import test_cmd
+from pythsol.cli.commands.verify import verify
+from pythsol.cli.commands.wallet import wallet
+
+
+@click.group(context_settings={"help_option_names": ["-h", "--help"]})
+@click.version_option(__version__, "--version", message="%(prog)s %(version)s")
+@click.option("--quiet", is_flag=True, help="Silence non-essential output.")
+@click.option("--verbose", is_flag=True, help="Show external commands that are run.")
+def cli(quiet: bool, verbose: bool) -> None:
+    """PythSol — Solana programs in typed Python."""
+    # Per-command implementations use these flags; Phase 1 only needs doctor.
+    _ = quiet, verbose
+
+
+def main(prog_name: str | None = None) -> None:
+    """Module entry point: "pythsol" or "pysol" depending on packaging aliases."""
+    prog = prog_name or os.path.basename(sys.argv[0]) or "pythsol"
+    cli(prog_name=prog)  # `Group.__call__` forwards to `Group.main(prog_name=prog)`.
+
+
+# Re-attach commands after the group definition so auto-help works uniformly.
+cli.add_command(doctor)
+cli.add_command(check)
+cli.add_command(emit_c)
+cli.add_command(build)
+cli.add_command(test_cmd)
+cli.add_command(init)
+cli.add_command(idl)
+cli.add_command(idl_publish)
+cli.add_command(client_cmd)
+cli.add_command(cpi_cmd)
+cli.add_command(deploy)
+cli.add_command(faucet)
+cli.add_command(wallet)
+cli.add_command(port_cmd)
+cli.add_command(verify)
+cli.add_command(profile)
+cli.add_command(docs)
+cli.add_command(serve)
+
+
+def _entrypoint() -> None:  # pragma: no cover — packaging script
+    main()
+
+
+if __name__ == "__main__":  # pragma: no cover
+    _entrypoint()

pythsol/cli/rpc.py

@@ -0,0 +1,56 @@
+"""JSON-RPC helper for faucet and wallet balance.
+
+The compiler never calls this. Commands that talk to a cluster the user named
+do. The body is a JSON-RPC request and the response is parsed as JSON.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+from urllib.error import HTTPError, URLError
+from urllib.request import Request, urlopen
+
+__all__ = ["RpcError", "post_json"]
+
+
+class RpcError(Exception):
+    """The endpoint refused the call or returned an error object."""
+
+
+def post_json(
+    url: str,
+    method: str,
+    params: list[object],
+    *,
+    timeout: float = 20.0,
+) -> dict[str, Any]:
+    """POST one JSON-RPC request and return the decoded object."""
+    payload = json.dumps({"jsonrpc": "2.0", "id": 1, "method": method, "params": params}).encode(
+        "utf-8"
+    )
+    request = Request(
+        url,
+        data=payload,
+        headers={"content-type": "application/json"},
+        method="POST",
+    )
+    try:
+        with urlopen(request, timeout=timeout) as response:
+            raw = response.read()
+    except HTTPError as exc:
+        detail = exc.read().decode("utf-8", errors="replace")
+        raise RpcError(detail or f"HTTP {exc.code}") from exc
+    except URLError as exc:
+        raise RpcError(str(exc.reason)) from exc
+    try:
+        body = json.loads(raw.decode("utf-8"))
+    except json.JSONDecodeError as exc:
+        raise RpcError("RPC response was not JSON") from exc
+    if not isinstance(body, dict):
+        raise RpcError("RPC response was not an object")
+    if "error" in body and body["error"] is not None:
+        error = body["error"]
+        message = error.get("message") if isinstance(error, dict) else str(error)
+        raise RpcError(str(message))
+    return body

pythsol/cli/template_programs/__init__.py

@@ -0,0 +1 @@
+"""Embedded `pythsol init` program sources. Read as text; do not import them."""

pythsol/cli/template_programs/counter.py

@@ -0,0 +1,52 @@
+# SPDX-License-Identifier: MIT
+"""A minimal PythSol program: an owned counter.
+
+`pythsol check programs/counter.py` must pass `mypy --strict` *and* the
+PythSol front-end. `pythsol build` (Phase 3) compiles it to native SBF.
+"""
+
+from pythsol import (
+    Init,
+    Mut,
+    ProgramError,
+    Pubkey,
+    Signer,
+    account,
+    error,
+    instruction,
+    require,
+    u8,
+    u64,
+)
+
+
+@account
+class Counter:
+    """The on-chain counter account layout."""
+
+    authority: Pubkey
+    count: u64
+    bump: u8
+
+
+@error
+class CounterError(ProgramError):
+    """Errors returned by this program (u32 codes)."""
+
+    Unauthorized = 100
+    Overflow = 101
+
+
+@instruction
+def initialize(authority: Signer, counter: Init[Counter], bump: u8) -> None:
+    """Create and initialize the counter authority fields."""
+    counter.authority = authority.key
+    counter.count = 0
+    counter.bump = bump
+
+
+@instruction
+def increment(authority: Signer, counter: Mut[Counter], by: u64) -> None:
+    """Add `by` to the count; only the stored authority may call this."""
+    require(counter.authority == authority.key, CounterError.Unauthorized)
+    counter.count += by

pythsol/cli/template_programs/escrow.py

@@ -0,0 +1,75 @@
+"""Escrow: one PDA deal funded in lamports.
+
+The seed is the literal ``escrow``, so a program has one open deal. ``make``
+creates it and transfers ``amount`` in. ``take`` pays the maker, then closes
+the account to the taker. ``cancel`` closes it back to the maker. A
+PDA-signed transfer is not available; closing the account is what returns
+the escrowed lamports.
+"""
+
+from pythsol import (
+    CloseTo,
+    Init,
+    Mut,
+    ProgramError,
+    Pubkey,
+    Seeds,
+    Signer,
+    account,
+    error,
+    instruction,
+    require,
+    system_transfer,
+    u8,
+    u64,
+)
+
+
+@account
+class Escrow:
+    maker: Pubkey
+    taker: Pubkey
+    amount: u64
+    bump: u8
+
+
+@error
+class EscrowError(ProgramError):
+    """Errors returned by this program (6000 + index)."""
+
+    Unauthorized = 100
+
+
+@instruction
+def make(
+    maker: Signer,
+    escrow: Seeds[Init[Escrow], "escrow"],  # type: ignore[name-defined]  # noqa: F821
+    taker: Pubkey,
+    bump: u8,
+    amount: u64,
+) -> None:
+    escrow.maker = maker.key
+    escrow.taker = taker
+    escrow.amount = amount
+    escrow.bump = bump
+    system_transfer(maker, escrow, amount)
+
+
+@instruction
+def take(
+    taker: Signer,
+    maker: Signer,
+    escrow: CloseTo[Mut[Escrow], taker],  # type: ignore[name-defined]  # noqa: F821
+    price: u64,
+) -> None:
+    require(escrow.taker == taker.key, EscrowError.Unauthorized)
+    require(escrow.maker == maker.key, EscrowError.Unauthorized)
+    system_transfer(taker, maker, price)
+
+
+@instruction
+def cancel(
+    maker: Signer,
+    escrow: CloseTo[Mut[Escrow], maker],  # type: ignore[name-defined]  # noqa: F821
+) -> None:
+    require(escrow.maker == maker.key, EscrowError.Unauthorized)

pythsol/cli/template_programs/ledger.py

@@ -0,0 +1,68 @@
+"""Ledger program: fixed slots, deposits, and a checked running total."""
+
+from pythsol import (
+    FixedArray,
+    Init,
+    Mut,
+    ProgramError,
+    Pubkey,
+    Signer,
+    account,
+    error,
+    instruction,
+    require,
+    u8,
+    u64,
+)
+
+
+@account
+class Ledger:
+    authority: Pubkey
+    total: u64
+    slots: FixedArray[u64, 4]  # type: ignore[valid-type]
+    bump: u8
+
+
+@error
+class LedgerError(ProgramError):
+    """Errors returned by this program (6000 + index)."""
+
+    Unauthorized = 100
+    BadSlot = 101
+    Insufficient = 102
+
+
+@instruction
+def initialize(authority: Signer, ledger: Init[Ledger], bump: u8) -> None:
+    ledger.authority = authority.key
+    ledger.total = 0
+    ledger.bump = bump
+
+
+@instruction
+def deposit(authority: Signer, ledger: Mut[Ledger], slot: u8, amount: u64) -> None:
+    require(ledger.authority == authority.key, LedgerError.Unauthorized)
+    require(slot < 4, LedgerError.BadSlot)
+    ledger.slots[slot] = ledger.slots[slot] + amount
+    ledger.total = ledger.total + amount
+
+
+@instruction
+def apply(authority: Signer, ledger: Mut[Ledger], amount: u64, mode: u8) -> None:
+    require(ledger.authority == authority.key, LedgerError.Unauthorized)
+    if mode == 0:
+        ledger.total = ledger.total + amount
+    else:
+        require(ledger.total >= amount, LedgerError.Insufficient)
+        ledger.total = ledger.total - amount
+
+
+@instruction
+def fill(authority: Signer, ledger: Mut[Ledger], value: u64) -> None:
+    require(ledger.authority == authority.key, LedgerError.Unauthorized)
+    total: u64 = 0
+    for i in range(4):
+        ledger.slots[i] = value
+        total = total + value
+    ledger.total = total

pythsol/cli/template_programs/multisig.py

@@ -0,0 +1,91 @@
+"""A 2-of-3 treasury. Owners approve a payout; the PDA signs the transfer."""
+
+from pythsol import (
+    FixedArray,
+    Init,
+    Mut,
+    ProgramError,
+    Pubkey,
+    Seeds,
+    Signer,
+    account,
+    error,
+    instruction,
+    require,
+    system_transfer,
+    u8,
+    u64,
+)
+
+
+@account
+class Treasury:
+    creator: Pubkey
+    owners: FixedArray[Pubkey, 3]
+    approvals: u8
+    threshold: u8
+    paid: u64
+    bump: u8
+
+
+@error
+class TreasuryError(ProgramError):
+    """Errors returned by this program (6000 + index)."""
+
+    Unauthorized = 100
+    BadSlot = 101
+    AlreadyApproved = 102
+    NotApproved = 103
+    Threshold = 104
+
+
+@instruction
+def initialize(
+    authority: Signer,
+    treasury: Seeds[Init[Treasury], "treasury"],  # type: ignore[name-defined]  # noqa: F821
+    first: Pubkey,
+    second: Pubkey,
+    third: Pubkey,
+    threshold: u8,
+    bump: u8,
+) -> None:
+    require(threshold >= 1, TreasuryError.Threshold)
+    require(threshold <= 3, TreasuryError.Threshold)
+    treasury.creator = authority.key
+    treasury.owners[0] = first
+    treasury.owners[1] = second
+    treasury.owners[2] = third
+    treasury.approvals = 0
+    treasury.threshold = threshold
+    treasury.paid = 0
+    treasury.bump = bump
+
+
+@instruction
+def fund(donor: Signer, treasury: Mut[Treasury], amount: u64) -> None:
+    system_transfer(donor, treasury, amount)
+
+
+@instruction
+def approve(owner: Signer, treasury: Mut[Treasury], slot: u8) -> None:
+    require(slot < 3, TreasuryError.BadSlot)
+    require(treasury.owners[slot] == owner.key, TreasuryError.Unauthorized)
+    mask: u8 = 1 << slot
+    require((treasury.approvals & mask) == 0, TreasuryError.AlreadyApproved)
+    treasury.approvals = treasury.approvals | mask
+
+
+@instruction
+def release(owner: Signer, treasury: Mut[Treasury], dest: Signer, slot: u8, amount: u64) -> None:
+    require(slot < 3, TreasuryError.BadSlot)
+    require(treasury.owners[slot] == owner.key, TreasuryError.Unauthorized)
+    mask: u8 = 1 << slot
+    require((treasury.approvals & mask) != 0, TreasuryError.NotApproved)
+    count: u8 = 0
+    for i in range(3):
+        if ((treasury.approvals >> i) & 1) == 1:
+            count = count + 1
+    require(count >= treasury.threshold, TreasuryError.Threshold)
+    treasury.approvals = 0
+    system_transfer(treasury, dest, amount)
+    treasury.paid = treasury.paid + amount

pythsol/cli/template_programs/poll.py

@@ -0,0 +1,70 @@
+"""A four-voter poll. Each allowlisted key votes once; the tally lives on chain."""
+
+from pythsol import (
+    FixedArray,
+    Init,
+    Mut,
+    ProgramError,
+    Pubkey,
+    Seeds,
+    Signer,
+    account,
+    error,
+    instruction,
+    require,
+    u8,
+    u32,
+)
+
+
+@account
+class Poll:
+    authority: Pubkey
+    voters: FixedArray[Pubkey, 4]
+    voted: u8
+    yes: u32
+    no: u32
+    bump: u8
+
+
+@error
+class PollError(ProgramError):
+    """Errors returned by this program (6000 + index)."""
+
+    BadSlot = 100
+    Unauthorized = 101
+    AlreadyVoted = 102
+
+
+@instruction
+def initialize(
+    authority: Signer,
+    poll: Seeds[Init[Poll], "poll"],  # type: ignore[name-defined]  # noqa: F821
+    first: Pubkey,
+    second: Pubkey,
+    third: Pubkey,
+    fourth: Pubkey,
+    bump: u8,
+) -> None:
+    poll.authority = authority.key
+    poll.voters[0] = first
+    poll.voters[1] = second
+    poll.voters[2] = third
+    poll.voters[3] = fourth
+    poll.voted = 0
+    poll.yes = 0
+    poll.no = 0
+    poll.bump = bump
+
+
+@instruction
+def vote(voter: Signer, poll: Mut[Poll], slot: u8, choice: bool) -> None:
+    require(slot < 4, PollError.BadSlot)
+    require(poll.voters[slot] == voter.key, PollError.Unauthorized)
+    mask: u8 = 1 << slot
+    require((poll.voted & mask) == 0, PollError.AlreadyVoted)
+    poll.voted = poll.voted | mask
+    if choice:
+        poll.yes = poll.yes + 1
+    else:
+        poll.no = poll.no + 1