samp-core 1.1.0__tar.gz

samp_core-1.1.0/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: samp-core
+Version: 1.1.0
+Summary: Substrate Account Messaging Protocol -- Python SDK
+License-Expression: MIT
+Project-URL: Repository, https://github.com/samp-org/samp
+Project-URL: Specification, https://github.com/samp-org/samp/blob/main/specs/samp.md
+Requires-Python: >=3.9
+Requires-Dist: samp-crypto
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: mypy; extra == "dev"

samp_core-1.1.0/README.md

@@ -0,0 +1,87 @@
+# samp
+
+Python implementation of [SAMP](https://github.com/samp-org/samp) (Substrate Account Messaging Protocol). Crypto operations use a native Rust extension via PyO3.
+
+## Install
+
+Requires a Rust toolchain for the native crypto extension.
+
+```
+pip install maturin
+cd python/samp-crypto && maturin develop && cd ../..
+cd python && pip install -e .
+```
+
+## Usage
+
+```python
+import os
+
+from samp import (
+    EncryptedRemark, Seed, decode_remark,
+    nonce_from_bytes, plaintext_from_bytes, pubkey_from_bytes, sr25519_signing_scalar,
+)
+from samp.encryption import compute_view_tag, decrypt, encrypt
+from samp.wire import ContentType, encode_encrypted, encode_public
+
+sender_seed = Seed.from_bytes(bytes.fromhex("e5be9a5092b81bca" + "00" * 24))
+recipient_pub = pubkey_from_bytes(bytes.fromhex("8eaf04151687736" + "0" + "00" * 24))
+
+# Public message
+remark = encode_public(recipient_pub, "Hello from Python")
+
+# Encrypted message
+nonce = nonce_from_bytes(os.urandom(12))
+plaintext = plaintext_from_bytes(b"Private message")
+ciphertext = encrypt(plaintext, recipient_pub, nonce, sender_seed)
+tag = compute_view_tag(sender_seed, recipient_pub, nonce)
+enc_remark = encode_encrypted(ContentType.ENCRYPTED, tag, nonce, ciphertext)
+
+# Decrypt
+recipient_seed = Seed.from_bytes(bytes(32))
+scalar = sr25519_signing_scalar(recipient_seed)
+parsed = decode_remark(enc_remark)
+assert isinstance(parsed, EncryptedRemark)
+clear = decrypt(parsed.ciphertext, parsed.nonce, scalar)
+```
+
+## API
+
+### Wire
+
+| Function | Description |
+|----------|-------------|
+| `encode_public` | Public message (`0x10`) |
+| `encode_encrypted` | Encrypted or thread message (`0x11`/`0x12`) |
+| `encode_channel_create` | Channel creation (`0x13`) |
+| `encode_channel_msg` | Channel message (`0x14`) |
+| `encode_group` | Group message (`0x15`) |
+| `decode_remark` | Parse any SAMP remark → `Remark` dataclass |
+| `encode_thread_content` / `decode_thread_content` | Thread plaintext (refs + body) |
+| `encode_channel_content` / `decode_channel_content` | Channel plaintext (refs + body) |
+| `decode_group_content` | Group plaintext (refs + body) |
+| `encode_group_members` / `decode_group_members` | Group member list |
+| `channel_ref_from_recipient` | Extract channel ref from recipient field |
+
+### Crypto
+
+| Function | Description |
+|----------|-------------|
+| `encrypt` / `decrypt` | 1:1 ECDH + ChaCha20-Poly1305 |
+| `decrypt_as_sender` | Sender self-decryption via sealed_to |
+| `encrypt_for_group` / `decrypt_from_group` | Multi-recipient encryption |
+| `sr25519_signing_scalar` | Derive signing scalar from sr25519 seed |
+| `public_from_seed` | Derive public key from seed |
+| `compute_view_tag` / `check_view_tag` | 1-byte recipient filter |
+| `unseal_recipient` | Recover recipient from sealed_to field |
+| `build_capsules` / `scan_capsules` | Group capsule construction and scanning |
+
+### Types
+
+`Remark` (dataclass), `SampError` (exception)
+
+## Test
+
+```
+pytest tests/ -v
+```

samp_core-1.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[project]
+name = "samp-core"
+version = "1.1.0"
+description = "Substrate Account Messaging Protocol -- Python SDK"
+license = "MIT"
+requires-python = ">=3.9"
+dependencies = ["samp-crypto"]
+
+[project.optional-dependencies]
+dev = ["pytest", "mypy"]
+
+[project.urls]
+Repository = "https://github.com/samp-org/samp"
+Specification = "https://github.com/samp-org/samp/blob/main/specs/samp.md"
+
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.package-data]
+samp = ["py.typed"]
+
+[tool.mypy]
+strict = true
+files = ["samp"]
+warn_unused_ignores = true
+no_implicit_optional = true
+disallow_untyped_defs = true
+
+[[tool.mypy.overrides]]
+module = "samp_crypto"
+ignore_missing_imports = true
+
+[tool.pyright]
+include = ["samp", "tests"]
+venvPath = ".."
+venv = ".venv"
+reportMissingTypeStubs = "none"

samp_core-1.1.0/samp/__init__.py

@@ -0,0 +1,243 @@
+from samp.encryption import (
+    ENCRYPTED_OVERHEAD,
+    build_capsules,
+    check_view_tag,
+    compute_view_tag,
+    decrypt,
+    decrypt_as_sender,
+    decrypt_from_group,
+    derive_group_ephemeral,
+    encrypt,
+    encrypt_for_group,
+    public_from_seed,
+    sr25519_sign,
+    sr25519_signing_scalar,
+    unseal_recipient,
+)
+from samp.error import SampError
+from samp.extrinsic import (
+    ChainParams,
+    ExtractedCall,
+    ExtrinsicError,
+    build_signed_extrinsic,
+    extract_call,
+    extract_signer,
+)
+from samp.metadata import (
+    ErrorEntry,
+    ErrorTable,
+    FieldNotFoundError,
+    Metadata,
+    MetadataError,
+    ScaleError,
+    StorageLayout,
+    StorageNotFoundError,
+)
+from samp.scale import decode_bytes, decode_compact, encode_compact
+from samp.secret import ContentKey, Seed, ViewScalar
+from samp.ss58 import decode as ss58_decode
+from samp.ss58 import encode as ss58_encode
+from samp.types import (
+    CAPSULE_SIZE,
+    CHANNEL_DESC_MAX,
+    CHANNEL_NAME_MAX,
+    SS58_PREFIX_KUSAMA,
+    SS58_PREFIX_POLKADOT,
+    SS58_PREFIX_SUBSTRATE_GENERIC,
+    BlockNumber,
+    BlockRef,
+    CallArgs,
+    CallIdx,
+    Capsules,
+    ChannelDescription,
+    ChannelName,
+    Ciphertext,
+    EphPubkey,
+    ExtIndex,
+    ExtrinsicBytes,
+    ExtrinsicNonce,
+    GenesisHash,
+    Nonce,
+    PalletIdx,
+    Plaintext,
+    Pubkey,
+    RemarkBytes,
+    Signature,
+    SpecVersion,
+    Ss58Address,
+    Ss58Prefix,
+    TxVersion,
+    ViewTag,
+    block_number_from_int,
+    call_args_from_bytes,
+    call_idx_from_int,
+    capsules_count,
+    capsules_from_bytes,
+    ciphertext_from_bytes,
+    eph_pubkey_from_bytes,
+    ext_index_from_int,
+    extrinsic_bytes_from_bytes,
+    extrinsic_nonce_from_int,
+    genesis_hash_from_bytes,
+    nonce_from_bytes,
+    pallet_idx_from_int,
+    plaintext_from_bytes,
+    pubkey_from_bytes,
+    pubkey_zero,
+    remark_bytes_from_bytes,
+    signature_from_bytes,
+    spec_version_from_int,
+    ss58_prefix_from_int,
+    tx_version_from_int,
+    view_tag_from_int,
+)
+from samp.wire import (
+    CHANNEL_HEADER_SIZE,
+    SAMP_VERSION,
+    THREAD_HEADER_SIZE,
+    ApplicationRemark,
+    ChannelCreateRemark,
+    ChannelRemark,
+    ContentType,
+    EncryptedRemark,
+    GroupRemark,
+    PublicRemark,
+    Remark,
+    ThreadRemark,
+    content_type_from_byte,
+    decode_channel_content,
+    decode_channel_create,
+    decode_group_content,
+    decode_group_members,
+    decode_remark,
+    decode_thread_content,
+    encode_channel_content,
+    encode_channel_create,
+    encode_channel_msg,
+    encode_encrypted,
+    encode_group,
+    encode_group_members,
+    encode_public,
+    encode_thread_content,
+    is_samp_remark,
+)
+
+__all__ = [
+    "SAMP_VERSION",
+    "ContentType",
+    "content_type_from_byte",
+    "is_samp_remark",
+    "CAPSULE_SIZE",
+    "CHANNEL_HEADER_SIZE",
+    "THREAD_HEADER_SIZE",
+    "CHANNEL_NAME_MAX",
+    "CHANNEL_DESC_MAX",
+    "ENCRYPTED_OVERHEAD",
+    "Remark",
+    "PublicRemark",
+    "EncryptedRemark",
+    "ThreadRemark",
+    "ChannelCreateRemark",
+    "ChannelRemark",
+    "GroupRemark",
+    "ApplicationRemark",
+    "SampError",
+    "encode_public",
+    "encode_encrypted",
+    "encode_channel_msg",
+    "encode_channel_create",
+    "encode_group",
+    "encode_group_members",
+    "decode_remark",
+    "decode_thread_content",
+    "decode_channel_content",
+    "decode_channel_create",
+    "decode_group_content",
+    "decode_group_members",
+    "encode_thread_content",
+    "encode_channel_content",
+    "sr25519_sign",
+    "sr25519_signing_scalar",
+    "public_from_seed",
+    "encrypt",
+    "decrypt",
+    "decrypt_as_sender",
+    "compute_view_tag",
+    "check_view_tag",
+    "unseal_recipient",
+    "derive_group_ephemeral",
+    "build_capsules",
+    "encrypt_for_group",
+    "decrypt_from_group",
+    "decode_compact",
+    "encode_compact",
+    "decode_bytes",
+    "Metadata",
+    "StorageLayout",
+    "ErrorEntry",
+    "ErrorTable",
+    "MetadataError",
+    "ScaleError",
+    "StorageNotFoundError",
+    "FieldNotFoundError",
+    "ChainParams",
+    "ExtractedCall",
+    "ExtrinsicError",
+    "build_signed_extrinsic",
+    "extract_signer",
+    "extract_call",
+    "Seed",
+    "ViewScalar",
+    "ContentKey",
+    "ss58_encode",
+    "ss58_decode",
+    "BlockNumber",
+    "BlockRef",
+    "CallArgs",
+    "CallIdx",
+    "Capsules",
+    "ChannelDescription",
+    "ChannelName",
+    "Ciphertext",
+    "EphPubkey",
+    "ExtIndex",
+    "ExtrinsicBytes",
+    "ExtrinsicNonce",
+    "GenesisHash",
+    "Nonce",
+    "PalletIdx",
+    "Plaintext",
+    "Pubkey",
+    "RemarkBytes",
+    "Signature",
+    "SpecVersion",
+    "Ss58Address",
+    "Ss58Prefix",
+    "TxVersion",
+    "ViewTag",
+    "SS58_PREFIX_KUSAMA",
+    "SS58_PREFIX_POLKADOT",
+    "SS58_PREFIX_SUBSTRATE_GENERIC",
+    "block_number_from_int",
+    "call_args_from_bytes",
+    "call_idx_from_int",
+    "capsules_count",
+    "capsules_from_bytes",
+    "ciphertext_from_bytes",
+    "eph_pubkey_from_bytes",
+    "ext_index_from_int",
+    "extrinsic_bytes_from_bytes",
+    "extrinsic_nonce_from_int",
+    "genesis_hash_from_bytes",
+    "nonce_from_bytes",
+    "pallet_idx_from_int",
+    "plaintext_from_bytes",
+    "pubkey_from_bytes",
+    "pubkey_zero",
+    "remark_bytes_from_bytes",
+    "signature_from_bytes",
+    "spec_version_from_int",
+    "ss58_prefix_from_int",
+    "tx_version_from_int",
+    "view_tag_from_int",
+]

samp_core-1.1.0/samp/encryption.py

@@ -0,0 +1,149 @@
+from __future__ import annotations
+
+from typing import Optional
+
+import samp_crypto
+
+from samp.error import SampError
+from samp.secret import ContentKey, Seed, ViewScalar
+from samp.types import (
+    Capsules,
+    Ciphertext,
+    EphPubkey,
+    Nonce,
+    Plaintext,
+    Pubkey,
+    Signature,
+    ViewTag,
+    capsules_from_bytes,
+    ciphertext_from_bytes,
+    eph_pubkey_from_bytes,
+    plaintext_from_bytes,
+    pubkey_from_bytes,
+    signature_from_bytes,
+    view_tag_from_int,
+)
+
+ENCRYPTED_OVERHEAD = 80
+
+
+def sr25519_sign(seed: Seed, message: bytes) -> Signature:
+    return signature_from_bytes(samp_crypto.sr25519_sign(seed.expose_secret(), message))
+
+
+def sr25519_signing_scalar(seed: Seed) -> ViewScalar:
+    return ViewScalar.from_bytes(samp_crypto.sr25519_signing_scalar(seed.expose_secret()))
+
+
+def public_from_seed(seed: Seed) -> Pubkey:
+    return pubkey_from_bytes(samp_crypto.public_from_seed(seed.expose_secret()))
+
+
+def encrypt(
+    plaintext: Plaintext,
+    recipient: Pubkey,
+    nonce: Nonce,
+    sender_seed: Seed,
+) -> Ciphertext:
+    return ciphertext_from_bytes(
+        samp_crypto.encrypt_content(plaintext, recipient, nonce, sender_seed.expose_secret())
+    )
+
+
+def decrypt(
+    ciphertext: Ciphertext,
+    nonce: Nonce,
+    signing_scalar: ViewScalar,
+) -> Plaintext:
+    return plaintext_from_bytes(
+        samp_crypto.decrypt_content(ciphertext, signing_scalar.expose_secret(), nonce)
+    )
+
+
+def decrypt_as_sender(
+    ciphertext: Ciphertext,
+    nonce: Nonce,
+    sender_seed: Seed,
+) -> Plaintext:
+    return plaintext_from_bytes(
+        samp_crypto.decrypt_as_sender(ciphertext, sender_seed.expose_secret(), nonce)
+    )
+
+
+def compute_view_tag(sender_seed: Seed, recipient: Pubkey, nonce: Nonce) -> ViewTag:
+    return view_tag_from_int(
+        samp_crypto.compute_view_tag(sender_seed.expose_secret(), recipient, nonce)
+    )
+
+
+def check_view_tag(ciphertext: Ciphertext, signing_scalar: ViewScalar) -> ViewTag:
+    return view_tag_from_int(samp_crypto.check_view_tag(signing_scalar.expose_secret(), ciphertext))
+
+
+def unseal_recipient(ciphertext: Ciphertext, nonce: Nonce, sender_seed: Seed) -> Pubkey:
+    return pubkey_from_bytes(
+        samp_crypto.unseal_recipient(ciphertext, sender_seed.expose_secret(), nonce)
+    )
+
+
+def derive_group_ephemeral(sender_seed: Seed, nonce: Nonce) -> bytes:
+    result: bytes = samp_crypto.derive_group_ephemeral(sender_seed.expose_secret(), nonce)
+    return result
+
+
+def build_capsules(
+    content_key: ContentKey,
+    member_pubkeys: list[Pubkey],
+    eph_scalar: bytes,
+    nonce: Nonce,
+) -> Capsules:
+    return capsules_from_bytes(
+        samp_crypto.build_capsules(
+            content_key.expose_secret(), list(member_pubkeys), eph_scalar, nonce
+        )
+    )
+
+
+def scan_capsules(
+    data: bytes,
+    eph_pubkey: EphPubkey,
+    my_scalar: ViewScalar,
+    nonce: Nonce,
+) -> Optional[tuple[int, ContentKey]]:
+    result = samp_crypto.scan_capsules(data, eph_pubkey, my_scalar.expose_secret(), nonce)
+    if result is None:
+        return None
+    idx, ck = result
+    return int(idx), ContentKey.from_bytes(bytes(ck))
+
+
+def encrypt_for_group(
+    plaintext: Plaintext,
+    member_pubkeys: list[Pubkey],
+    nonce: Nonce,
+    sender_seed: Seed,
+) -> tuple[EphPubkey, Capsules, Ciphertext]:
+    eph, caps, ct = samp_crypto.encrypt_for_group(
+        plaintext, list(member_pubkeys), nonce, sender_seed.expose_secret()
+    )
+    return (
+        eph_pubkey_from_bytes(eph),
+        capsules_from_bytes(caps),
+        ciphertext_from_bytes(ct),
+    )
+
+
+def decrypt_from_group(
+    content: bytes,
+    my_scalar: ViewScalar,
+    nonce: Nonce,
+    known_n: Optional[int] = None,
+) -> Plaintext:
+    try:
+        return plaintext_from_bytes(
+            samp_crypto.decrypt_from_group(content, my_scalar.expose_secret(), nonce, known_n)
+        )
+    except SampError:
+        raise
+    except Exception as e:
+        raise SampError(f"decryption failed: {e}") from e

samp_core-1.1.0/samp/error.py

@@ -0,0 +1,2 @@
+class SampError(Exception):
+    pass

samp_core-1.1.0/samp/extrinsic.py

@@ -0,0 +1,154 @@
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass
+from typing import Callable, Optional
+
+from samp.scale import decode_compact, encode_compact
+from samp.types import (
+    CallArgs,
+    CallIdx,
+    ExtrinsicBytes,
+    ExtrinsicNonce,
+    GenesisHash,
+    PalletIdx,
+    Pubkey,
+    SpecVersion,
+    TxVersion,
+    call_args_from_bytes,
+    call_idx_from_int,
+    extrinsic_bytes_from_bytes,
+    pallet_idx_from_int,
+    pubkey_from_bytes,
+    signature_from_bytes,
+)
+
+EXT_VERSION_SIGNED = 0x84
+ADDR_TYPE_ID = 0x00
+SIG_TYPE_SR25519 = 0x01
+ERA_IMMORTAL = 0x00
+METADATA_HASH_DISABLED = 0x00
+SIGNED_HEADER_LEN = 99
+MIN_SIGNED_EXTRINSIC = 103
+MIN_SIGNER_PAYLOAD = 34
+
+
+class ExtrinsicError(Exception):
+    pass
+
+
+@dataclass(frozen=True)
+class ChainParams:
+    genesis_hash: GenesisHash
+    spec_version: SpecVersion
+    tx_version: TxVersion
+
+
+@dataclass(frozen=True)
+class ExtractedCall:
+    pallet: PalletIdx
+    call: CallIdx
+    args: CallArgs
+
+
+def build_signed_extrinsic(
+    pallet_idx: PalletIdx,
+    call_idx: CallIdx,
+    call_args: CallArgs,
+    public_key: Pubkey,
+    sign: Callable[[bytes], bytes],
+    nonce: ExtrinsicNonce,
+    chain_params: ChainParams,
+) -> ExtrinsicBytes:
+    call_data = bytes([int(pallet_idx), int(call_idx)]) + call_args
+    tip = bytes([0])
+
+    signing_payload = (
+        call_data
+        + bytes([ERA_IMMORTAL])
+        + encode_compact(int(nonce))
+        + tip
+        + bytes([METADATA_HASH_DISABLED])
+        + int(chain_params.spec_version).to_bytes(4, "little")
+        + int(chain_params.tx_version).to_bytes(4, "little")
+        + chain_params.genesis_hash
+        + chain_params.genesis_hash
+        + bytes([0x00])
+    )
+
+    if len(signing_payload) > 256:
+        to_sign = hashlib.blake2b(signing_payload, digest_size=32).digest()
+    else:
+        to_sign = signing_payload
+
+    signature = signature_from_bytes(sign(to_sign))
+
+    extrinsic_payload = (
+        bytes([EXT_VERSION_SIGNED, ADDR_TYPE_ID])
+        + public_key
+        + bytes([SIG_TYPE_SR25519])
+        + signature
+        + bytes([ERA_IMMORTAL])
+        + encode_compact(int(nonce))
+        + tip
+        + bytes([METADATA_HASH_DISABLED])
+        + call_data
+    )
+
+    return extrinsic_bytes_from_bytes(encode_compact(len(extrinsic_payload)) + extrinsic_payload)
+
+
+def extract_signer(extrinsic_bytes: ExtrinsicBytes) -> Optional[Pubkey]:
+    decoded = decode_compact(extrinsic_bytes)
+    if decoded is None:
+        return None
+    _, prefix_len = decoded
+    payload = extrinsic_bytes[prefix_len:]
+    if (
+        len(payload) < MIN_SIGNER_PAYLOAD
+        or payload[0] & 0x80 == 0
+        or payload[1] != ADDR_TYPE_ID
+    ):
+        return None
+    return pubkey_from_bytes(payload[2:34])
+
+
+def extract_call(extrinsic_bytes: ExtrinsicBytes) -> Optional[ExtractedCall]:
+    decoded = decode_compact(extrinsic_bytes)
+    if decoded is None:
+        return None
+    _, prefix_len = decoded
+    payload = extrinsic_bytes[prefix_len:]
+
+    if len(payload) < MIN_SIGNED_EXTRINSIC or payload[0] & 0x80 == 0:
+        return None
+
+    offset = SIGNED_HEADER_LEN
+    if payload[offset] != 0x00:
+        offset += 2
+    else:
+        offset += 1
+
+    nonce = decode_compact(payload[offset:])
+    if nonce is None:
+        return None
+    offset += nonce[1]
+
+    tip = decode_compact(payload[offset:])
+    if tip is None:
+        return None
+    offset += tip[1]
+
+    offset += 1
+
+    if offset + 2 > len(payload):
+        return None
+    pallet = payload[offset]
+    call = payload[offset + 1]
+    offset += 2
+
+    return ExtractedCall(
+        pallet=pallet_idx_from_int(pallet),
+        call=call_idx_from_int(call),
+        args=call_args_from_bytes(payload[offset:]),
+    )