cashscript-py 1.0.0__py3-none-any.whl

cashscript_py/__init__.py

@@ -0,0 +1,36 @@
+"""Public API for CashScript-Py.
+
+Exports the most commonly used classes and helpers:
+- Contract
+- Output, Utxo
+- ElectrumNetworkProvider, NetworkProvider
+- SignatureTemplate
+- TransactionBuilder
+"""
+
+from cashscript_py.contract import Contract
+from cashscript_py.helpers.argument_encoding import ConstructorArgument, FunctionArgument
+from cashscript_py.helpers.cashaddress import LockingBytecodeType
+from cashscript_py.interfaces import HashType, NftCapability, Output, SignatureAlgorithm, TokenDetails, Utxo
+from cashscript_py.network.electrum_network_provider import ElectrumNetworkProvider
+from cashscript_py.network.network_provider import Network, NetworkProvider
+from cashscript_py.signature_template import SignatureTemplate
+from cashscript_py.transaction_builder import TransactionBuilder
+
+__all__ = [
+    "Contract",
+    "Output",
+    "Utxo",
+    "ElectrumNetworkProvider",
+    "Network",
+    "NetworkProvider",
+    "SignatureTemplate",
+    "TransactionBuilder",
+    "LockingBytecodeType",
+    "ConstructorArgument",
+    "FunctionArgument",
+    "HashType",
+    "SignatureAlgorithm",
+    "TokenDetails",
+    "NftCapability",
+]

cashscript_py/contract.py

@@ -0,0 +1,210 @@
+"""Contract API.
+
+Provides loading and interaction with CashScript-contract artifacts, including
+constructor validation/encoding, address generation, and ABI-based unlockers.
+"""
+
+import os
+
+from collections.abc import Callable
+from typing import Any
+
+import semver
+
+from cashscript_py.helpers.address import script_to_address
+from cashscript_py.helpers.argument_encoding import (
+    ConstructorArgument,
+    FunctionArgument,
+    encode_constructor_arguments,
+    encode_function_argument,
+)
+from cashscript_py.helpers.cashaddress import LockingBytecodeType, address_string_to_locking_bytecode
+from cashscript_py.helpers.crypto import hash256
+from cashscript_py.helpers.script import (
+    asm_to_script,
+    calculate_bytesize,
+    count_opcodes,
+    create_input_script,
+    generate_redeem_script,
+    serialize_script,
+)
+from cashscript_py.helpers.transaction import create_preimage
+from cashscript_py.interfaces import ContractUnlocker, Output, Transaction, Utxo
+from cashscript_py.network.network_provider import NetworkProvider
+from cashscript_py.signature_template import SignatureTemplate
+
+
+class Contract:
+    """High-level interface to a CashScript contract.
+
+    A Contract is constructed from a compiled cashc JSON artifact and constructor
+    arguments. It exposes ABI functions via the `unlock` mapping and provides
+    helper methods for querying UTXOs and balances.
+
+    Attributes:
+        name: The contract name from the artifact.
+        address: The contract address (token-unaware).
+        token_address: The contract address (token-aware).
+        bytecode: Contract redeem script bytecode (hex).
+        bytesize: Size of the redeem script in bytes.
+        opcount: Count of non-push opcodes in the redeem script.
+        provider: Network provider used for blockchain operations.
+        address_type: Locking bytecode type (e.g., P2SH32).
+        unlock: Mapping of function name to unlocker factory.
+
+    """
+
+    def __init__(
+        self,
+        artifact: dict[str, Any],
+        constructor_args: list[ConstructorArgument],
+        provider: NetworkProvider,
+        address_type: LockingBytecodeType = LockingBytecodeType.P2SH32,
+    ):
+        """Initialize a Contract instance.
+
+        Args:
+            artifact: The compiled cashc JSON artifact.
+            constructor_args: Constructor arguments in ABI order.
+            provider: Network provider for queries and broadcasts.
+            address_type: Locking bytecode type to use for addresses (Default: P2SH32).
+
+        Raises:
+            ValueError: If the artifact is incomplete/invalid, the compiler
+                version is unsupported (< 0.7.0), or the constructor argument
+                count/types do not match the artifact.
+
+        """
+        self.artifact = artifact
+        self.constructor_args: list[ConstructorArgument] = constructor_args
+        self.provider = provider
+        self.address_type = address_type
+
+        required_fields = ["abi", "bytecode", "constructorInputs", "contractName", "compiler"]
+        for field in required_fields:
+            if field not in artifact or artifact[field] is None:
+                raise ValueError(f"Missing {field}")
+
+        version = artifact["compiler"]["version"]
+        if not semver.VersionInfo.parse(version).match(">=0.7.0"):
+            raise ValueError(f"Artifact compiled with unsupported compiler version: {version}, required >=0.7.0")
+
+        if len(artifact["constructorInputs"]) != len(constructor_args):
+            expected_types = [input["type"] for input in artifact["constructorInputs"]]
+            raise ValueError(
+                f"Incorrect number of arguments passed to {artifact['contractName']} constructor. "
+                f"Expected {len(artifact['constructorInputs'])} arguments ({expected_types}) "
+                f"but got {len(constructor_args)}"
+            )
+
+        self.encoded_constructor_args: list[bytes] = encode_constructor_arguments(
+            constructor_args, artifact["constructorInputs"]
+        )
+        self.redeem_script = generate_redeem_script(asm_to_script(artifact["bytecode"]), self.encoded_constructor_args)
+
+        self.name = artifact["contractName"]
+        self.address = script_to_address(self.redeem_script, self.provider.network, self.address_type, False)
+        self.token_address = script_to_address(self.redeem_script, self.provider.network, self.address_type, True)
+        self.bytecode = serialize_script(self.redeem_script).hex()
+        self.bytesize = calculate_bytesize(self.redeem_script)
+        self.opcount = count_opcodes(self.redeem_script)
+        self.unlock: dict[str, Callable[..., ContractUnlocker]] = {}
+
+        if len(artifact["abi"]) == 1:
+            f = artifact["abi"][0]
+            self.unlock[f["name"]] = self._create_unlocker(f)
+        else:
+            for i, f in enumerate(artifact["abi"]):
+                self.unlock[f["name"]] = self._create_unlocker(f, i)
+
+    def _create_unlocker(
+        self, abi_function: dict[str, Any], selector: int | None = None
+    ) -> Callable[..., ContractUnlocker]:
+        def unlocker(*args: FunctionArgument) -> ContractUnlocker:
+            if len(abi_function["inputs"]) != len(args):
+                expected_types = [inp["type"] for inp in abi_function["inputs"]]
+                raise ValueError(
+                    f"Incorrect number of arguments passed to function {abi_function['name']}. "
+                    f"Expected {len(abi_function['inputs'])} arguments ({expected_types}) "
+                    f"but got {len(args)}"
+                )
+
+            encoded_args = [
+                encode_function_argument(arg, abi_function["inputs"][i]["type"]) for i, arg in enumerate(args)
+            ]
+
+            def generate_unlocking_bytecode(
+                transaction: Transaction, source_outputs: list[Output], input_index: int
+            ) -> bytes:
+                complete_args = []
+
+                for arg in encoded_args:
+                    if isinstance(arg, SignatureTemplate):
+                        # Build preimage and sighash (SIGHASH_UTXOS path handled by create_preimage)
+                        hashtype_full = arg.get_hash_type().value
+                        covered_script = serialize_script(self.redeem_script)
+                        preimage = create_preimage(
+                            transaction, source_outputs, input_index, covered_script, hashtype_full
+                        )
+                        sighash = hash256(preimage)
+
+                        # Generate signature (sig + hashtype byte) for CHECKSIG
+                        signature = arg.generate_signature(sighash)
+
+                        # Debugging info
+                        if os.environ.get("CASHSCRIPT_PY_DEBUG") == "1":
+                            print(f"[contract-debug] function={abi_function.get('name')}")
+                            print(
+                                f"[contract-debug] hashtype_byte=0x{(hashtype_full & 0xFF):02x} "
+                                f"algo={arg.get_signature_algorithm().name}"
+                            )
+                            print(f"[contract-debug] preimage: {preimage.hex()}")
+                            print(f"[contract-debug] sighash:  {sighash.hex()}")
+                            print(f"[contract-debug] signature: {signature.hex()}")
+
+                        complete_args.append(signature)
+                    else:
+                        complete_args.append(arg)
+
+                # Create input script
+                input_script = create_input_script(self.redeem_script, complete_args, selector)
+
+                # Debugging info
+                if os.environ.get("CASHSCRIPT_PY_DEBUG") == "1":
+                    redeem_bc = serialize_script(self.redeem_script)
+                    print(f"[contract-debug] redeem_script_bytecode: {redeem_bc.hex()}")
+                    print(f"[contract-debug] input_script_bytecode:  {input_script.hex()}")
+
+                return input_script
+
+            def generate_locking_bytecode() -> bytes:
+                return address_string_to_locking_bytecode(self.address)
+
+            return ContractUnlocker(
+                generate_locking_bytecode,
+                generate_unlocking_bytecode,
+                self,
+                list(args),
+                abi_function,
+            )
+
+        return unlocker
+
+    async def get_balance(self) -> int:
+        """Return the total balance (sum of UTXO satoshis) at the contract address.
+
+        Returns:
+            The sum of satoshis across all UTXOs at the contract address.
+
+        """
+        utxos = await self.get_utxos()
+        return sum(utxo.satoshis for utxo in utxos)
+
+    async def get_utxos(self) -> list[Utxo]:
+        """Fetch all UTXOs (confirmed/unconfirmed) for the contract address.
+
+        Returns:
+            A list of UTXOs spendable by this contract.
+
+        """
+        return await self.provider.get_utxos(self.address)

cashscript_py/helpers/__init__.py

@@ -0,0 +1 @@
+"""Helper subpackage: address, script, encoding, crypto, and token utilities."""

cashscript_py/helpers/address.py

@@ -0,0 +1,95 @@
+"""Utility functions for address computations, conversions, and transformations."""
+
+from cashscript_py.helpers.cashaddress import (
+    LockingBytecodeType,
+    address_contents_to_locking_bytecode,
+    get_network_prefix,
+    locking_bytecode_to_cash_address,
+    payload_to_cash_address,
+)
+from cashscript_py.helpers.crypto import hash160, hash256
+from cashscript_py.helpers.script import Script, serialize_script
+from cashscript_py.network.network_provider import Network
+
+
+def script_to_address(
+    script: Script, network: Network, address_type: LockingBytecodeType, token_aware: bool = False
+) -> str:
+    """Convert a script to a CashAddress for the given network/type.
+
+    Args:
+        script: Script list to encode.
+        network: Target network.
+        address_type: Locking bytecode type (P2SH20/P2SH32/P2PKH/P2PK).
+        token_aware: If True, encode token-aware address version.
+
+    Returns:
+        CashAddress string.
+
+    """
+    locking_bytecode = script_to_locking_bytecode(script, address_type)
+    prefix = get_network_prefix(network)
+    return locking_bytecode_to_cash_address(locking_bytecode, prefix, token_aware)
+
+
+def script_to_locking_bytecode(script: Script, address_type: LockingBytecodeType) -> bytes:
+    """Hash a script into its P2SH20/P2SH32 (or P2PKH/P2PK) locking bytecode.
+
+    Args:
+        script: Script list to hash.
+        address_type: Desired locking type.
+
+    Returns:
+        Locking bytecode.
+
+    Raises:
+        ValueError: If the address_type is unsupported.
+
+    """
+    if address_type != LockingBytecodeType.P2SH20 and address_type != LockingBytecodeType.P2SH32:
+        raise ValueError("address_type needs to be either 'p2sh32' or 'p2sh20'")
+    script_bytecode = serialize_script(script)
+    script_hash = hash256(script_bytecode) if address_type == LockingBytecodeType.P2SH32 else hash160(script_bytecode)
+    return address_contents_to_locking_bytecode(script_hash, address_type)
+
+
+def public_key_to_pkh(public_key: bytes) -> bytes:
+    """Return the HASH160 of a public key (pkh)."""
+    return hash160(public_key)
+
+
+def public_key_to_p2pkh_locking_bytecode(public_key: bytes) -> bytes:
+    """Build a standard P2PKH locking bytecode from a public key.
+
+    Args:
+        public_key: Raw public key (compressed or uncompressed).
+
+    Returns:
+        P2PKH locking bytecode.
+
+    """
+    pubkey_hash: bytes = hash160(public_key)
+    return address_contents_to_locking_bytecode(pubkey_hash, LockingBytecodeType.P2PKH)
+
+
+def public_key_to_cash_address(
+    public_key: bytes,
+    network: Network,
+    address_type: LockingBytecodeType = LockingBytecodeType.P2PKH,
+    token_aware: bool = False,
+) -> str:
+    """Convert a public key to a CashAddress.
+
+    Args:
+        public_key: Raw public key (compressed or uncompressed).
+        network: Target network.
+        address_type: Address type (default P2PKH).
+        token_aware: If True, uses token-aware address version.
+
+    Returns:
+        CashAddress string.
+
+    """
+    prefix = get_network_prefix(network)
+    public_key_hash = hash160(public_key)
+    return payload_to_cash_address(prefix, public_key_hash, address_type, token_aware)

cashscript_py/helpers/argument_encoding.py

@@ -0,0 +1,161 @@
+"""CashScript ABI argument encoding.
+
+Key behavior:
+- 'int' encodes to Script Number (little-endian, minimal-length).
+- 'bool' encodes to 0x00/0x01.
+- 'string' encodes to UTF-8 bytes.
+- 'pubkey' accepts raw bytes or hex string (33/65 bytes).
+- 'bytes'/'bytesN' accept raw bytes or hex string; bytesN enforces exact length.
+- 'sig' accepts SignatureTemplate, or raw bytes with valid lengths {0,65,71,72,73}.
+- 'datasig' accepts raw bytes with valid lengths {0,64,70,71,72}.
+"""
+
+from typing import cast
+
+from cashscript_py.helpers.script import encode_int as encode_script_number
+from cashscript_py.signature_template import SignatureTemplate
+
+
+class ArgumentTypeError(Exception):
+    """Raised when an ABI argument's Python type does not match the expected CashScript type."""
+
+    def __init__(self, actual_type: str, expected_type: str):
+        """Initialize the type error with actual and expected type names."""
+        super().__init__(f"Expected type `{expected_type}` but got `{actual_type}`")
+
+
+ConstructorArgument = bool | int | str | bytes
+FunctionArgument = ConstructorArgument | SignatureTemplate
+
+
+def _parse_type(type_str: str) -> tuple[str, int | None]:
+    """Parse a CashScript type string.
+
+    Args:
+        type_str: Type string (e.g., "int", "bytes", "bytes20", "pubkey", "sig").
+
+    Returns:
+        A tuple of (base_type, bound) where bound is the integer size for bytesN or None.
+
+    """
+    import re
+
+    m = re.match(r"bytes(\d+)$", type_str)
+    if m:
+        return ("bytes", int(m.group(1)))
+    return (type_str, None)
+
+
+def _encode_bool(value: bool) -> bytes:
+    return b"\x01" if value else b"\x00"
+
+
+def _encode_string(value: str) -> bytes:
+    return value.encode("utf-8")
+
+
+def _encode_pubkey(value: bytes | str) -> bytes:
+    return value if isinstance(value, bytes) else bytes.fromhex(value)
+
+
+def encode_constructor_arguments(
+    contract_params: list[ConstructorArgument], constructor_inputs: list[dict[str, str]]
+) -> list[bytes]:
+    """Encode constructor arguments according to the artifact's constructor types.
+
+    Args:
+        contract_params: Values provided to the contract constructor.
+        constructor_inputs: Type descriptors (in declaration order) from the artifact.
+
+    Returns:
+        Encoded arguments as raw bytes (ABI format).
+
+    Raises:
+        ValueError: If a signature type is used in the constructor (disallowed) or types mismatch.
+
+    """
+    if "sig" in [i["type"] for i in constructor_inputs]:
+        raise ValueError("Cannot use signatures in constructor")
+    return [
+        cast(bytes, encode_function_argument(value, arg["type"]))
+        for value, arg in zip(contract_params, constructor_inputs, strict=False)
+    ]
+
+
+def encode_function_argument(argument: FunctionArgument, type_str: str) -> bytes | SignatureTemplate:
+    """Encode a single function argument for the CashScript ABI.
+
+    Args:
+        argument: The argument value (bytes/hex/string/int/bool/SigTemplate).
+        type_str: The ABI type string (e.g., "int", "bool", "string", "bytesN", "pubkey", "sig", "datasig").
+
+    Returns:
+        Encoded bytes or a SignatureTemplate (for "sig").
+
+    Raises:
+        ArgumentTypeError: If the value type does not match the expected ABI type.
+        ValueError: If bounded bytesN lengths, signature lengths, or unknown types are invalid.
+
+    """
+
+    # Normalize to bytes (convert hex string to bytes)
+    def _normalize_bytes(value: FunctionArgument) -> bool | int | bytes | SignatureTemplate:
+        if isinstance(value, str):
+            value = value[2:] if value.startswith("0x") else value
+            value = bytes.fromhex(value)
+        return value
+
+    t, bound = _parse_type(type_str)
+
+    # Special handling for signature-like types
+    if t == "sig":
+        if isinstance(argument, SignatureTemplate):
+            return argument
+        argument = _normalize_bytes(argument)
+        if not isinstance(argument, bytes):
+            raise ArgumentTypeError(type(argument).__name__, "sig")
+        # Allowed lengths: NULLFAIL (0), Schnorr+hashtype (65), ECDSA DER+hashtype (71/72/73)
+        if len(argument) not in {0, 65, 71, 72, 73}:
+            raise ValueError(f"Expected sig length in {{0,65,71,72,73}} but got {len(argument)}")
+        return argument
+
+    if t == "datasig":
+        argument = _normalize_bytes(argument)
+        if not isinstance(argument, bytes):
+            raise ArgumentTypeError(type(argument).__name__, "datasig")
+        # Allowed lengths: NULLFAIL (0), Schnorr (64), ECDSA DER (70/71/72)
+        if len(argument) not in {0, 64, 70, 71, 72}:
+            raise ValueError(f"Expected datasig length in {{0,64,70,71,72}} but got {len(argument)}")
+        return argument
+
+    if t == "int":
+        if not isinstance(argument, int):
+            raise ArgumentTypeError(type(argument).__name__, "int")
+        return bytes(encode_script_number(argument))
+
+    if t == "bool":
+        if not isinstance(argument, bool):
+            raise ArgumentTypeError(type(argument).__name__, "bool")
+        return _encode_bool(argument)
+
+    if t == "string":
+        if not isinstance(argument, str):
+            raise ArgumentTypeError(type(argument).__name__, "string")
+        return _encode_string(argument)
+
+    if t == "pubkey":
+        if not isinstance(argument, (bytes, str)):
+            raise ArgumentTypeError(type(argument).__name__, "pubkey")
+        return _encode_pubkey(argument)
+
+    if t == "bytes":
+        # Ensure correct type first – use the full type_str (e.g., 'bytes20') in error for clarity
+        argument = _normalize_bytes(argument)
+        if not isinstance(argument, bytes):
+            raise ArgumentTypeError(type(argument).__name__, type_str)
+        # Enforce bounded length for bytesN
+        if bound is not None and len(argument) != bound:
+            raise ValueError(f"Expected bytes of length {bound} for type `{type_str}` but got {len(argument)}")
+        return argument
+
+    raise ValueError(f"Unknown type: {type_str}")