pythsol 0.1.0__py3-none-any.whl

pythsol/__init__.py

@@ -0,0 +1,317 @@
+"""Typed DSL surface that programs import from.
+
+This file is intentionally *importable only as types*: the compiler parses the
+import with `ast` and never executes it, while mypy/pyright use it to
+type-check programs (`py.typed` marker lives beside the package). Phase 3 adds
+the actual runtime semantics — this slice is what Phase 2 accepts.
+
+Every program may import:
+  * width types:  u8,u16,u32,u64,u128 and i8..i128
+  * atoms:        bool, Pubkey, Signer, SystemProgram
+  * wrappers:     Mut[T], Init[T], InitIfNeeded[T], Zeroed[T], Account[T]
+  * collections:  Option[T], Vec[T], FixedArray[T, N], FixedString[N]
+  * decorators:   @instruction, @account, @struct, @event, @error, @enum
+  * accounts:     TokenAccount (writable), TokenMint (read-only), no owner check
+  * helpers:      require, emit, system_transfer, token_transfer,
+                  token2022_transfer, ata_create
+  * `ProgramError` base class
+"""
+
+from __future__ import annotations
+
+from typing import Any, Generic, TypeAlias, TypeVar
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Account",
+    "Address",
+    "CloseTo",
+    "FixedArray",
+    "FixedString",
+    "HasOne",
+    "Init",
+    "InitIfNeeded",
+    "Mut",
+    "Option",
+    "Owner",
+    "ProgramError",
+    "Pubkey",
+    "Seeds",
+    "Signer",
+    "SystemProgram",
+    "TokenAccount",
+    "TokenMint",
+    "Vec",
+    "Zeroed",
+    "account",
+    "ata_create",
+    "emit",
+    "enum",
+    "error",
+    "event",
+    "i8",
+    "i16",
+    "i32",
+    "i64",
+    "i128",
+    "instruction",
+    "require",
+    "struct",
+    "system_transfer",
+    "token2022_transfer",
+    "token_transfer",
+    "u8",
+    "u16",
+    "u32",
+    "u64",
+    "u128",
+]
+
+_T = TypeVar("_T")
+_N = TypeVar("_N")
+
+# widths ---------------------------------------------------------------
+u8: TypeAlias = int
+u16: TypeAlias = int
+u32: TypeAlias = int
+u64: TypeAlias = int
+u128: TypeAlias = int
+i8: TypeAlias = int
+i16: TypeAlias = int
+i32: TypeAlias = int
+i64: TypeAlias = int
+i128: TypeAlias = int
+
+
+# atoms ----------------------------------------------------------------
+class Pubkey:
+    """An opaque 32-byte on-chain identity."""
+
+    key: Pubkey
+
+
+class Signer(Pubkey):
+    """Binding contract: this account must be a required signer."""
+
+    key: Pubkey
+
+
+class SystemProgram:
+    """Anchor `system_program` stand-in used as a `@account Permissioned type`."""
+
+    program_id: Pubkey
+
+
+class TokenAccount:
+    """A writable SPL token account. The program does not check its owner."""
+
+
+class TokenMint:
+    """A read-only mint. The program does not check its owner."""
+
+
+class ProgramError:
+    """Base class of `@error` program errors."""
+
+    message: str | None = None
+
+
+# wrappers -------------------------------------------------------------
+class Mut(Generic[_T]):
+    """Flag: this instruction can write to the wrapped type."""
+
+    def __getattribute__(self, name: str) -> Any:  # pragma: no cover
+        ...
+
+    def __setattr__(self, name: str, value: Any) -> None:  # pragma: no cover
+        ...
+
+
+class Init(Mut[_T]):
+    """Marks this instruction as the one that initializes the account."""
+
+
+class InitIfNeeded(Mut[_T]):
+    """New-account-or-existing? Runtime-conditional."""
+
+
+class Zeroed(Mut[_T]):
+    """The account must be zeroed before this instruction runs."""
+
+
+class Account(Generic[_T]):
+    """Read-only account wrapper."""
+
+    def __getattribute__(self, name: str) -> Any:  # pragma: no cover
+        ...
+
+
+class Seeds(Generic[_T, _N]):
+    """``Seeds[Init[T], "seed"]`` — the PDA seed, instead of the account name.
+
+    The second argument is a string literal. Type checkers treat that literal
+    as a forward reference, so a program line carries ``type: ignore`` and
+    ``noqa: F821``. Attribute access is untyped, like ``Mut``.
+    """
+
+    def __getattribute__(self, name: str) -> Any:  # pragma: no cover
+        ...
+
+    def __setattr__(self, name: str, value: Any) -> None:  # pragma: no cover
+        ...
+
+
+class HasOne(Generic[_T, _N]):
+    """``HasOne[Mut[T], "field"]`` — ``account.field`` equals that account's key."""
+
+    def __getattribute__(self, name: str) -> Any:  # pragma: no cover
+        ...
+
+    def __setattr__(self, name: str, value: Any) -> None:  # pragma: no cover
+        ...
+
+
+class CloseTo(Generic[_T, _N]):
+    """``CloseTo[Mut[T], dest]`` — after a successful body, lamports move to ``dest``."""
+
+    def __getattribute__(self, name: str) -> Any:  # pragma: no cover
+        ...
+
+    def __setattr__(self, name: str, value: Any) -> None:  # pragma: no cover
+        ...
+
+
+class Address(Generic[_T, _N]):
+    """``Address[Account[T], expected]`` — the account key equals a ``Pubkey`` argument."""
+
+    def __getattribute__(self, name: str) -> Any:  # pragma: no cover
+        ...
+
+
+class Owner(Generic[_T, _N]):
+    """``Owner[Account[T], program]`` — ``account.owner`` equals that account's key."""
+
+    def __getattribute__(self, name: str) -> Any:  # pragma: no cover
+        ...
+
+
+# collections ----------------------------------------------------------
+class Option(Generic[_T]):
+    """Fixed-width optional value: a tag byte plus the inner value, always reserved.
+
+    ``None`` clears the tag. Assigning a ``T`` sets it. ``.is_some`` reads the
+    tag; ``.value`` reads the inner value and aborts when the tag is clear.
+    This is not Borsh's short ``None`` (one zero byte). Later fields stay put.
+    """
+
+    def __getattribute__(self, name: str) -> Any:  # pragma: no cover
+        ...
+
+
+class Vec(Generic[_T]):
+    """Account-resizing vector (Anchor `Vec[T]`)."""
+
+    def __getattribute__(self, name: str) -> Any:  # pragma: no cover
+        ...
+
+
+class FixedArray(Generic[_T, _N]):
+    """Fixed-length typed array. ``N`` in ``FixedArray[T, N]`` is an integer literal."""
+
+    def __getattribute__(self, name: str) -> Any:  # pragma: no cover
+        ...
+
+
+class FixedString(Generic[_N]):
+    """Fixed-width string: a ``u32`` byte length plus ``N`` reserved bytes.
+
+    Store a string literal whose UTF-8 form fits in ``N``. ``len`` reads the
+    stored byte count. This is not Borsh's short string: the ``N`` bytes stay
+    reserved so later fields do not move.
+    """
+
+    def __getattribute__(self, name: str) -> Any:  # pragma: no cover
+        ...
+
+
+# decorators -----------------------------------------------------------
+def instruction(func: Any) -> Any:
+    """Mark a function as an instruction entry point."""
+    return func
+
+
+def account(value: Any) -> Any:
+    """Mark a class as a program-local account layout."""
+    return value
+
+
+def error(value: Any) -> Any:
+    """Mark a class as an on-chain error."""
+    return value
+
+
+def enum(value: Any) -> Any:
+    """Mark a class as a one-byte unit enum (``Name = <declaration index>``)."""
+    return value
+
+
+def struct(value: Any) -> Any:
+    """Mark a class as a fixed-layout value nested inside an account."""
+    return value
+
+
+def event(value: Any) -> Any:
+    """Mark a class as a fixed-width value logged by ``emit``."""
+    return value
+
+
+def token_transfer(src: object, dest: object, authority: object, amount: int) -> None:
+    """SPL Token Transfer (instruction 3) from ``src`` to ``dest``."""
+    del src, dest, authority, amount
+
+
+def token2022_transfer(src: object, dest: object, authority: object, amount: int) -> None:
+    """Token-2022 Transfer (instruction 3). Same accounts as ``token_transfer``."""
+    del src, dest, authority, amount
+
+
+def ata_create(payer: object, ata: object, owner: object, mint: object) -> None:
+    """Create an associated token account (idempotent). Uses the SPL Token program."""
+    del payer, ata, owner, mint
+
+
+def system_transfer(src: object, dest: object, lamports: int) -> None:
+    """Move lamports with a System-program transfer CPI.
+
+    ``src`` and ``dest`` are a ``Signer`` or a ``Mut`` account, and they must
+    differ. The generated client appends the System program account.
+    """
+    del src, dest, lamports
+
+
+def emit(value: object) -> None:
+    """Log one ``@event``. The compiler lowers the call; this stub does not.
+
+    Write ``emit(Name(field, ...))`` with one positional argument per field,
+    in declaration order. The on-chain log is the 8-byte event discriminator
+    (``sha256("event:Name")[..8]``) followed by the packed fields.
+    """
+    del value
+
+
+class InstructionError(ProgramError):
+    """Recommended base for @error classes used via `require(cond, cls.name)`."""
+
+
+def require(condition: bool, err: object) -> None:
+    """Fail the instruction immediately if the condition is false.
+
+    The compiler front-end reads calls to this helper statically; `err` must be
+    a member of an ``@error`` class (e.g. ``require(cond, MyErr.Bad)``). The
+    static check is what enforces that; the Python signature stays permissive
+    so the decorator surface type-checks with plain mypy/pyright.
+    """
+
+    if condition is not True:  # pragma: no cover
+        raise err  # type: ignore[misc]  # DSL stub: real semantics live in the compiled C.

pythsol/cli/__init__.py

@@ -0,0 +1,7 @@
+"""Expose pythsol.cli (click command group)."""
+
+from __future__ import annotations
+
+from pythsol.cli.main import cli, main
+
+__all__ = ["cli", "main"]

pythsol/cli/cache.py

@@ -0,0 +1,78 @@
+"""Content-addressed cache for the SBF ``.so``.
+
+The key is the generated C, the compiler version, the clang version, the
+runtime header, and a flavor tag. A hit copies the ``.so`` and skips clang.
+The C text is part of the key so an emitter change is a miss even when the
+package version stays ``0.1.0``.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+from pathlib import Path
+
+from pythsol import __version__
+
+__all__ = ["artifact_key", "cache_directory", "lookup_so", "store_so"]
+
+#: Bump when compile or link flags change but the C text might not.
+CACHE_FLAVOR = "sbf-o2-gc-strip-v1"
+
+
+def cache_directory() -> Path | None:
+    """Return the cache root, or ``None`` when caching is off.
+
+    ``PYTHSOL_NO_CACHE=1`` disables it. ``PYTHSOL_CACHE`` (or ``PYSOL_CACHE``)
+    overrides the default directory.
+    """
+    flag = os.environ.get("PYTHSOL_NO_CACHE", "").strip().lower()
+    if flag in {"1", "true", "yes"}:
+        return None
+    override = os.environ.get("PYTHSOL_CACHE") or os.environ.get("PYSOL_CACHE")
+    if override:
+        return Path(override).expanduser()
+    local = os.environ.get("LOCALAPPDATA")
+    if local:
+        return Path(local) / "pythsol" / "cache"
+    return Path.home() / ".cache" / "pythsol"
+
+
+def artifact_key(
+    *,
+    c_text: str,
+    clang_version: str,
+    arch: str,
+    runtime_header: bytes,
+) -> str:
+    """sha256 of everything that changes the linked ``.so``."""
+    digest = hashlib.sha256()
+    digest.update(b"pythsol-cache\0")
+    digest.update(CACHE_FLAVOR.encode())
+    digest.update(b"\0")
+    digest.update(__version__.encode())
+    digest.update(b"\0")
+    digest.update(clang_version.encode())
+    digest.update(b"\0")
+    digest.update(arch.encode())
+    digest.update(b"\0")
+    digest.update(hashlib.sha256(runtime_header).digest())
+    digest.update(c_text.encode())
+    return digest.hexdigest()
+
+
+def lookup_so(root: Path, key: str) -> Path | None:
+    """Return a cached ``.so`` for ``key``, or ``None``."""
+    path = root / key / "program.so"
+    if path.is_file() and path.stat().st_size > 0:
+        return path
+    return None
+
+
+def store_so(root: Path, key: str, so_path: Path) -> None:
+    """Copy ``so_path`` into the cache. A crash mid-write leaves the old file."""
+    dest_dir = root / key
+    dest_dir.mkdir(parents=True, exist_ok=True)
+    temporary = dest_dir / "program.so.tmp"
+    temporary.write_bytes(so_path.read_bytes())
+    temporary.replace(dest_dir / "program.so")

pythsol/cli/cluster.py

@@ -0,0 +1,45 @@
+"""Cluster names and RPC URLs shared by deploy, faucet, and wallet."""
+
+from __future__ import annotations
+
+import os
+
+__all__ = ["DEVNET_URL", "is_mainnet", "resolve_url"]
+
+DEVNET_URL = "https://api.devnet.solana.com"
+MAINNET_URL = "https://api.mainnet-beta.solana.com"
+LOCALHOST_URL = "http://127.0.0.1:8899"
+TESTNET_URL = "https://api.testnet.solana.com"
+
+_ALIASES = {
+    "devnet": DEVNET_URL,
+    "localhost": LOCALHOST_URL,
+    "localnet": LOCALHOST_URL,
+    "mainnet": MAINNET_URL,
+    "mainnet-beta": MAINNET_URL,
+    "testnet": TESTNET_URL,
+}
+
+_MAINNET = {
+    MAINNET_URL.rstrip("/").lower(),
+    "https://api.mainnet.solana.com",
+}
+
+
+def resolve_url(value: str | None) -> str:
+    """Turn a cluster name or URL into an RPC URL.
+
+    An empty value uses ``PYSOL_RPC_URL`` or ``PYTHSOL_RPC_URL``, then devnet.
+    """
+    if value is None or value.strip() == "":
+        env = os.environ.get("PYSOL_RPC_URL") or os.environ.get("PYTHSOL_RPC_URL")
+        if env:
+            return resolve_url(env)
+        return DEVNET_URL
+    key = value.strip()
+    return _ALIASES.get(key.lower(), key)
+
+
+def is_mainnet(value: str) -> bool:
+    """True for mainnet aliases and the public mainnet RPC URL."""
+    return resolve_url(value).rstrip("/").lower() in _MAINNET

pythsol/cli/commands/build.py

@@ -0,0 +1,214 @@
+"""`pythsol build PROGRAM.py` — C → SBF `.so` + IDL + manifest."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import shutil
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+import click
+
+from pythsol import __version__
+from pythsol.cli.cache import artifact_key, cache_directory, lookup_so, store_so
+from pythsol.client.gen import render_client
+from pythsol.compiler.diagnostics import Diagnostic, PysolError
+from pythsol.compiler.idl import idl_json
+from pythsol.compiler.modules import read_sibling_modules
+from pythsol.compiler.pipeline import emit_program
+from pythsol.runtime import HEADER_NAME, RUNTIME_INCLUDE_DIR
+
+
+class BuildFailed(Exception):  # noqa: N818
+    """The program did not pass the compiler. ``diagnostics`` is non-empty."""
+
+    def __init__(self, diagnostics: list[Diagnostic]) -> None:
+        self.diagnostics = diagnostics
+        super().__init__(f"{len(diagnostics)} diagnostics")
+
+
+@dataclass(frozen=True)
+class BuiltProgram:
+    """Paths written by one successful build."""
+
+    name: str
+    workdir: Path
+    c_path: Path
+    so_path: Path
+    idl_path: Path
+    client_path: Path
+    manifest_path: Path
+    #: ``hit`` skipped clang, ``miss`` compiled, ``off`` cache disabled.
+    cache: str
+
+
+def build_program(
+    program: Path,
+    out: Path | None = None,
+    name: str | None = None,
+) -> BuiltProgram:
+    """Compile ``program`` and return the artifact paths.
+
+    Raises :class:`BuildFailed` for diagnostics, :class:`OSError` when a
+    source file cannot be read, and :class:`PysolError` when clang is missing
+    or the link fails.
+    """
+    source_text = program.read_text(encoding="utf-8", errors="replace")
+    modules, module_files = read_sibling_modules(program)
+    generated = emit_program(
+        source_text,
+        program,
+        name=name,
+        modules=modules,
+        module_files=module_files,
+    )
+    if not generated.ok or generated.generated is None:
+        raise BuildFailed(list(generated.diagnostics))
+
+    workdir = (out or Path("target/pythsol") / generated.name).resolve()
+    workdir.mkdir(parents=True, exist_ok=True)
+
+    c_path = workdir / f"{generated.name}.c"
+    c_path.write_text(generated.c_text, encoding="utf-8", newline="\n")
+
+    from pythsol.compiler import toolchain
+
+    toolpaths = toolchain.locate_platform_tools(None)
+    if toolpaths is None:
+        raise PysolError(
+            code="PS4010",
+            message="no SBF platform-tools found; cannot finish the build",
+            fix="run `pythsol doctor`; set PYTHSOL_SBF_SDK or install Agave "
+            "platform-tools (CI Linux runners are the supported path)",
+        )
+
+    header_path = RUNTIME_INCLUDE_DIR / HEADER_NAME
+    header = header_path.read_bytes()
+    key = artifact_key(
+        c_text=generated.c_text,
+        clang_version=toolpaths.version or "unknown",
+        arch=toolpaths.arch,
+        runtime_header=header,
+    )
+    root = cache_directory()
+    cached = lookup_so(root, key) if root is not None else None
+    so_path = workdir / f"{generated.name}.so"
+    if cached is not None:
+        shutil.copyfile(cached, so_path)
+        cache = "hit"
+    else:
+        so_path = toolchain.compile_to_sbf(
+            toolpaths,
+            c_path,
+            workdir,
+            include_dirs=(RUNTIME_INCLUDE_DIR,),
+        )
+        if root is not None:
+            store_so(root, key, so_path)
+        cache = "miss" if root is not None else "off"
+
+    idl_path = workdir / f"{generated.name}.json"
+    idl_path.write_text(idl_json(generated.generated), encoding="utf-8", newline="\n")
+
+    client_path = workdir / f"{generated.name}_client.py"
+    client_path.write_text(
+        render_client(generated.generated),
+        encoding="utf-8",
+        newline="\n",
+    )
+
+    manifest = {
+        "generator": f"pythsol {__version__}",
+        "program": generated.name,
+        "source": generated.source_file,
+        "entrypoint": "entrypoint",
+        "cache": cache,
+        "files": {
+            "c": c_path.name,
+            "idl": idl_path.name,
+            "so": so_path.name,
+            "client": client_path.name,
+        },
+        "sha256": {
+            "c": _sha256(c_path),
+            "idl": _sha256(idl_path),
+            "so": _sha256(so_path),
+            "client": _sha256(client_path),
+        },
+        "toolchain": {
+            "arch": toolpaths.arch,
+            "clang": toolpaths.version or "unknown",
+        },
+    }
+    manifest_path = workdir / "manifest.json"
+    manifest_path.write_text(
+        json.dumps(manifest, indent=2, sort_keys=True) + "\n",
+        encoding="utf-8",
+        newline="\n",
+    )
+    return BuiltProgram(
+        name=generated.name,
+        workdir=workdir,
+        c_path=c_path,
+        so_path=so_path,
+        idl_path=idl_path,
+        client_path=client_path,
+        manifest_path=manifest_path,
+        cache=cache,
+    )
+
+
+@click.command(name="build")
+@click.argument(
+    "program",
+    metavar="PROGRAM.py",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+)
+@click.option(
+    "--out",
+    type=click.Path(file_okay=False, path_type=Path),
+    default=None,
+    help="Output directory (default: target/pythsol/<name>).",
+)
+@click.option(
+    "--name",
+    default=None,
+    help="Program name (default: the file stem).",
+)
+def build(program: Path, out: Path | None, name: str | None) -> None:
+    """Compile a PythSol program to a native SBF `.so`, IDL and manifest.
+
+    Produces ``<name>.c`` (generated C), ``<name>.so`` (the on-chain ELF),
+    ``<name>.json`` (IDL), ``<name>_client.py`` (solders builders) and
+    ``manifest.json`` with sha256 hashes. Builds are byte-deterministic
+    for identical input. A second build of the same C skips clang when the
+    cache is on.
+    """
+    try:
+        built = build_program(program, out=out, name=name)
+    except OSError as os_error:
+        click.echo(f"error: cannot read {program}: {os_error}", err=True)
+        sys.exit(2)
+    except BuildFailed as failed:
+        for diagnostic in failed.diagnostics:
+            click.echo(diagnostic.render(), err=True)
+        sys.exit(1)
+    except PysolError as error:
+        click.echo(error.render(), err=True)
+        sys.exit(1)
+
+    click.echo(f"build: {program} -> {built.so_path}")
+    if built.cache == "hit":
+        click.echo("build: cache hit (skipped clang)")
+    elif built.cache == "miss":
+        click.echo("build: cache miss")
+    click.echo(f"build: idl -> {built.idl_path}")
+    click.echo(f"build: client -> {built.client_path}")
+    click.echo(f"build: manifest -> {built.manifest_path}")
+    sys.exit(0)
+
+
+def _sha256(path: Path) -> str:
+    return hashlib.sha256(path.read_bytes()).hexdigest()