aptos-ace-sdk 3.11.1__tar.gz

aptos_ace_sdk-3.11.1/.gitignore

@@ -0,0 +1,9 @@
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.venv/
+__pycache__/
+*.py[cod]
+dist/
+build/
+*.egg-info/

aptos_ace_sdk-3.11.1/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.5
+Name: aptos-ace-sdk
+Version: 3.11.1
+Summary: Python SDK for ACE (mirrors @aptos-labs/ace-sdk)
+License: Apache-2.0
+Requires-Python: >=3.10
+Requires-Dist: aptos-sdk>=0.11.0
+Requires-Dist: cryptography>=46.0.0
+Requires-Dist: py-ecc>=8.0.0
+Requires-Dist: pyhpke>=0.6.0
+Requires-Dist: pynacl<2,>=1.5.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ACE Python SDK
+
+Python SDK for ACE (Aptos Confidential Extension). This package mirrors the
+core crypto and wire-format surface of `@aptos-labs/ace-sdk` for Python
+callers.
+
+The SDK currently includes:
+
+- BCS helpers for the wire formats ACE uses.
+- Scheme-tagged BLS12-381 G1/G2 group wrappers.
+- Feldman/Shamir VSS helpers.
+- Pedersen polynomial commitments, DKG and DKR state decoders.
+- Public-key encryption schemes used by ACE.
+- Scheme-tagged Ed25519 signing helpers for reconstructor/admin flows.
+- Threshold IBE primitives.
+- Known deployment metadata and network state view decoders.
+- Discovery snapshot decoding for the keyless discovery service.
+- Aptos IBE encryption helpers.
+- Worker decryption request helpers for basic and custom flows.
+- Disaster-recovery master-secret reconstruction helpers.
+- Aptos threshold-VRF request, share verification, and output reconstruction helpers.
+
+## Install for local development
+
+```bash
+python -m venv .venv
+.venv/bin/python -m pip install -e '.[dev]'
+```
+
+## Quick check
+
+```python
+from ace_sdk import pke
+
+encryption_key, decryption_key = pke.keygen()
+ciphertext = pke.encrypt(encryption_key, b"hello ace")
+plaintext = pke.decrypt(decryption_key, ciphertext).unwrap_or_throw("decrypt failed")
+assert plaintext == b"hello ace"
+```
+
+The API follows Python naming conventions (`from_bytes`, `to_hex`,
+`derive_encryption_key`) while preserving ACE's byte-level compatibility with
+the TypeScript SDK.
+
+The default PKE scheme is HPKE and does not require native system libraries.
+The legacy `ElGamalOtpRistretto255` scheme requires libsodium >= 1.0.18 with
+the `crypto_core_ristretto255_*` APIs. Install it with your system package
+manager, or set `ACE_SDK_LIBSODIUM_PATH` to the library path.
+
+## Admin IBE validation
+
+The reconstructed master secret printed by the ACE disaster-recovery flow is a
+32-byte little-endian Fr scalar. Use it to extract a full identity decryption
+key and validate a ciphertext:
+
+```python
+from ace_sdk import t_ibe
+
+idk = t_ibe.extract(msk_scalar=msk_scalar, identity=label).unwrap_or_throw("extract")
+plaintext = t_ibe.decrypt([idk], ciphertext).unwrap_or_throw("decrypt")
+```
+
+For Aptos app encryption, `ibe_aptos.encrypt` builds the same full decryption
+domain as the TypeScript SDK before t-IBE encryption.
+
+## Benchmarks
+
+The BLS12-381 pairing implementation is pure Python and intentionally kept out
+of the default test suite. Run its opt-in benchmark with:
+
+```bash
+python benchmarks/bench_pairing.py --iterations 5
+```
+
+## Aptos custom flow
+
+For custom access-control flows, callers provide the application proof payload
+and the PKE keypair that workers should use to encrypt returned IDK shares:
+
+```python
+from ace_sdk import ibe_aptos, pke
+
+enc_pk, enc_sk = pke.keygen()
+plaintext = ibe_aptos.decrypt_custom_flow(
+    ace_deployment=deployment,
+    keypair_id=keypair_id,
+    chain_id=chain_id,
+    module_addr=module_addr,
+    module_name="example",
+    label=b"object-id",
+    enc_pk=enc_pk,
+    enc_sk=enc_sk,
+    payload=custom_proof_payload,
+    ciphertext=ciphertext_bytes,
+).unwrap_or_throw("custom decrypt")
+```

aptos_ace_sdk-3.11.1/README.md

@@ -0,0 +1,96 @@
+# ACE Python SDK
+
+Python SDK for ACE (Aptos Confidential Extension). This package mirrors the
+core crypto and wire-format surface of `@aptos-labs/ace-sdk` for Python
+callers.
+
+The SDK currently includes:
+
+- BCS helpers for the wire formats ACE uses.
+- Scheme-tagged BLS12-381 G1/G2 group wrappers.
+- Feldman/Shamir VSS helpers.
+- Pedersen polynomial commitments, DKG and DKR state decoders.
+- Public-key encryption schemes used by ACE.
+- Scheme-tagged Ed25519 signing helpers for reconstructor/admin flows.
+- Threshold IBE primitives.
+- Known deployment metadata and network state view decoders.
+- Discovery snapshot decoding for the keyless discovery service.
+- Aptos IBE encryption helpers.
+- Worker decryption request helpers for basic and custom flows.
+- Disaster-recovery master-secret reconstruction helpers.
+- Aptos threshold-VRF request, share verification, and output reconstruction helpers.
+
+## Install for local development
+
+```bash
+python -m venv .venv
+.venv/bin/python -m pip install -e '.[dev]'
+```
+
+## Quick check
+
+```python
+from ace_sdk import pke
+
+encryption_key, decryption_key = pke.keygen()
+ciphertext = pke.encrypt(encryption_key, b"hello ace")
+plaintext = pke.decrypt(decryption_key, ciphertext).unwrap_or_throw("decrypt failed")
+assert plaintext == b"hello ace"
+```
+
+The API follows Python naming conventions (`from_bytes`, `to_hex`,
+`derive_encryption_key`) while preserving ACE's byte-level compatibility with
+the TypeScript SDK.
+
+The default PKE scheme is HPKE and does not require native system libraries.
+The legacy `ElGamalOtpRistretto255` scheme requires libsodium >= 1.0.18 with
+the `crypto_core_ristretto255_*` APIs. Install it with your system package
+manager, or set `ACE_SDK_LIBSODIUM_PATH` to the library path.
+
+## Admin IBE validation
+
+The reconstructed master secret printed by the ACE disaster-recovery flow is a
+32-byte little-endian Fr scalar. Use it to extract a full identity decryption
+key and validate a ciphertext:
+
+```python
+from ace_sdk import t_ibe
+
+idk = t_ibe.extract(msk_scalar=msk_scalar, identity=label).unwrap_or_throw("extract")
+plaintext = t_ibe.decrypt([idk], ciphertext).unwrap_or_throw("decrypt")
+```
+
+For Aptos app encryption, `ibe_aptos.encrypt` builds the same full decryption
+domain as the TypeScript SDK before t-IBE encryption.
+
+## Benchmarks
+
+The BLS12-381 pairing implementation is pure Python and intentionally kept out
+of the default test suite. Run its opt-in benchmark with:
+
+```bash
+python benchmarks/bench_pairing.py --iterations 5
+```
+
+## Aptos custom flow
+
+For custom access-control flows, callers provide the application proof payload
+and the PKE keypair that workers should use to encrypt returned IDK shares:
+
+```python
+from ace_sdk import ibe_aptos, pke
+
+enc_pk, enc_sk = pke.keygen()
+plaintext = ibe_aptos.decrypt_custom_flow(
+    ace_deployment=deployment,
+    keypair_id=keypair_id,
+    chain_id=chain_id,
+    module_addr=module_addr,
+    module_name="example",
+    label=b"object-id",
+    enc_pk=enc_pk,
+    enc_sk=enc_sk,
+    payload=custom_proof_payload,
+    ciphertext=ciphertext_bytes,
+).unwrap_or_throw("custom decrypt")
+```

aptos_ace_sdk-3.11.1/benchmarks/bench_pairing.py

@@ -0,0 +1,49 @@
+# Copyright (c) Aptos Labs
+# SPDX-License-Identifier: Apache-2.0
+"""Small opt-in benchmark for the pure-Python BLS12-381 pairing."""
+
+from __future__ import annotations
+
+import argparse
+import statistics
+import time
+
+from ace_sdk.group import bls12381g1, bls12381g2
+from ace_sdk.group.bls12381_pairing import fp12_to_bytes, pairing_from_jacobian
+
+
+def measure_pairing(iterations: int) -> list[float]:
+    g1 = bls12381g1.g1_generator().pt
+    g2 = bls12381g2.g2_generator().pt
+    timings_ms: list[float] = []
+    for _ in range(iterations):
+        start = time.perf_counter()
+        result = pairing_from_jacobian(g1, g2)
+        fp12_to_bytes(result)
+        timings_ms.append((time.perf_counter() - start) * 1000)
+    return timings_ms
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "-n",
+        "--iterations",
+        type=int,
+        default=5,
+        help="number of pairing operations to measure",
+    )
+    args = parser.parse_args()
+    if args.iterations < 1:
+        raise ValueError("iterations must be >= 1")
+
+    measure_pairing(1)
+    timings_ms = measure_pairing(args.iterations)
+    mean_ms = statistics.fmean(timings_ms)
+    print(f"pairing_from_jacobian+fp12_to_bytes: {mean_ms:.2f} ms/op")
+    print(f"iterations={args.iterations} min={min(timings_ms):.2f} max={max(timings_ms):.2f}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

aptos_ace_sdk-3.11.1/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "aptos-ace-sdk"
+version = "3.11.1"
+description = "Python SDK for ACE (mirrors @aptos-labs/ace-sdk)"
+readme = "README.md"
+license = { text = "Apache-2.0" }
+requires-python = ">=3.10"
+dependencies = [
+  "aptos-sdk>=0.11.0",
+  "cryptography>=46.0.0",
+  "PyNaCl>=1.5.0,<2",
+  "py_ecc>=8.0.0",
+  "pyhpke>=0.6.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ace_sdk"]

aptos_ace_sdk-3.11.1/src/ace_sdk/__init__.py

@@ -0,0 +1,46 @@
+# Copyright (c) Aptos Labs
+# SPDX-License-Identifier: Apache-2.0
+"""ACE Python SDK public package entrypoint."""
+
+from ace_sdk import (
+    dkg,
+    dkr,
+    group,
+    known_deployments,
+    network,
+    pedersen_polynomial_commitment,
+    pke,
+    sig,
+    sigma_dlog_linear,
+    t_ibe,
+    vrf_aptos,
+    vss,
+)
+from ace_sdk import admin_recovery, decryption, ibe_aptos
+from ace_sdk._internal.deployment import AceDeployment
+from ace_sdk._internal.discovery import DiscoveryViewV0
+from ace_sdk._internal.common import ContractID, FullDecryptionDomain
+from ace_sdk.result import Result
+
+__all__ = [
+    "AceDeployment",
+    "ContractID",
+    "DiscoveryViewV0",
+    "FullDecryptionDomain",
+    "Result",
+    "admin_recovery",
+    "decryption",
+    "dkg",
+    "dkr",
+    "group",
+    "ibe_aptos",
+    "known_deployments",
+    "network",
+    "pedersen_polynomial_commitment",
+    "pke",
+    "sig",
+    "sigma_dlog_linear",
+    "t_ibe",
+    "vrf_aptos",
+    "vss",
+]

aptos_ace_sdk-3.11.1/src/ace_sdk/_internal/__init__.py

@@ -0,0 +1,3 @@
+# Copyright (c) Aptos Labs
+# SPDX-License-Identifier: Apache-2.0
+"""Internal package mirroring src/_internal/*.ts (common, aptos, solana, deployment)."""

aptos_ace_sdk-3.11.1/src/ace_sdk/_internal/aptos.py

@@ -0,0 +1,296 @@
+# Copyright (c) Aptos Labs
+# SPDX-License-Identifier: Apache-2.0
+"""Mirrors src/_internal/aptos.ts.
+
+Only BCS wire-format (serialize/deserialize) is implemented for every Aptos
+public-key/signature scheme: actual signature *verification* happens
+server-side (Move contract / worker), never in this SDK, so we do not need
+real crypto verification logic here -- just byte-exact encode/decode for
+every variant a wallet might produce (Ed25519, AnyPublicKey/SingleKey
+[Secp256k1, Secp256r1, Keyless, FederatedKeyless], MultiEd25519, MultiKey,
+Keyless, FederatedKeyless).
+"""
+
+from __future__ import annotations
+
+from aptos_sdk.account_address import AccountAddress
+
+from ace_sdk.bcs import (
+    Deserializer,
+    Serializer,
+    deserialize_account_address,
+    deserialize_option,
+    deserialize_option_str,
+    deserialize_vector,
+    serialize_account_address,
+    serialize_option,
+    serialize_vector,
+)
+from ace_sdk.result import Result
+
+# == Ed25519 ===================================================================
+
+
+class Ed25519PublicKey:
+    LENGTH = 32
+
+    def __init__(self, key: bytes) -> None:
+        if len(key) != self.LENGTH:
+            raise ValueError(f"Ed25519PublicKey length should be {self.LENGTH}")
+        self.key = key
+
+    def serialize(self, serializer: Serializer) -> None:
+        serializer.serialize_bytes(self.key)
+
+    @staticmethod
+    def deserialize(deserializer: Deserializer) -> "Ed25519PublicKey":
+        return Ed25519PublicKey(deserializer.deserialize_bytes())
+
+
+class Ed25519Signature:
+    LENGTH = 64
+
+    def __init__(self, data: bytes) -> None:
+        if len(data) != self.LENGTH:
+            raise ValueError(f"Ed25519Signature length should be {self.LENGTH}")
+        self.data = data
+
+    def serialize(self, serializer: Serializer) -> None:
+        serializer.serialize_bytes(self.data)
+
+    @staticmethod
+    def deserialize(deserializer: Deserializer) -> "Ed25519Signature":
+        return Ed25519Signature(deserializer.deserialize_bytes())
+
+
+# == Secp256k1 ==================================================================
+
+
+class Secp256k1PublicKey:
+    LENGTH = 65
+    COMPRESSED_LENGTH = 33
+
+    def __init__(self, key: bytes) -> None:
+        if len(key) == self.LENGTH:
+            self.key = key
+        elif len(key) == self.COMPRESSED_LENGTH:
+            import ecdsa
+
+            point = ecdsa.VerifyingKey.from_string(key, curve=ecdsa.SECP256k1).pubkey.point
+            x = point.x().to_bytes(32, "big")
+            y = point.y().to_bytes(32, "big")
+            self.key = b"\x04" + x + y
+        else:
+            raise ValueError(
+                f"Secp256k1PublicKey length should be {self.LENGTH} or "
+                f"{self.COMPRESSED_LENGTH}, received {len(key)}"
+            )
+
+    def serialize(self, serializer: Serializer) -> None:
+        serializer.serialize_bytes(self.key)
+
+    @staticmethod
+    def deserialize(deserializer: Deserializer) -> "Secp256k1PublicKey":
+        return Secp256k1PublicKey(deserializer.deserialize_bytes())
+
+
+class Secp256k1Signature:
+    LENGTH = 64
+
+    def __init__(self, data: bytes) -> None:
+        if len(data) != self.LENGTH:
+            raise ValueError(f"Secp256k1Signature length should be {self.LENGTH}")
+        self.data = data
+
+    def serialize(self, serializer: Serializer) -> None:
+        serializer.serialize_bytes(self.data)
+
+    @staticmethod
+    def deserialize(deserializer: Deserializer) -> "Secp256k1Signature":
+        return Secp256k1Signature(deserializer.deserialize_bytes())
+
+
+# == Secp256r1 (WebAuthn / passkeys) ============================================
+
+
+class Secp256r1PublicKey:
+    LENGTH = 65
+    COMPRESSED_LENGTH = 33
+
+    def __init__(self, key: bytes) -> None:
+        if len(key) == self.COMPRESSED_LENGTH:
+            import ecdsa
+
+            point = ecdsa.VerifyingKey.from_string(key, curve=ecdsa.NIST256p).pubkey.point
+            x = point.x().to_bytes(32, "big")
+            y = point.y().to_bytes(32, "big")
+            self.key = b"\x04" + x + y
+        elif len(key) == self.LENGTH:
+            self.key = key
+        else:
+            raise ValueError(
+                f"Secp256r1PublicKey length should be {self.LENGTH} or "
+                f"{self.COMPRESSED_LENGTH}, received {len(key)}"
+            )
+
+    def serialize(self, serializer: Serializer) -> None:
+        serializer.serialize_bytes(self.key)
+
+    @staticmethod
+    def deserialize(deserializer: Deserializer) -> "Secp256r1PublicKey":
+        return Secp256r1PublicKey(deserializer.deserialize_bytes())
+
+
+class Secp256r1Signature:
+    LENGTH = 64
+
+    def __init__(self, data: bytes) -> None:
+        if len(data) != self.LENGTH:
+            raise ValueError(f"Secp256r1Signature length should be {self.LENGTH}")
+        self.data = data
+
+    def serialize(self, serializer: Serializer) -> None:
+        serializer.serialize_bytes(self.data)
+
+    @staticmethod
+    def deserialize(deserializer: Deserializer) -> "Secp256r1Signature":
+        return Secp256r1Signature(deserializer.deserialize_bytes())
+
+
+class WebAuthnSignature:
+    def __init__(
+        self, signature: bytes, authenticator_data: bytes, client_data_json: bytes
+    ) -> None:
+        self.signature = signature
+        self.authenticator_data = authenticator_data
+        self.client_data_json = client_data_json
+
+    def serialize(self, serializer: Serializer) -> None:
+        serializer.serialize_u32_as_uleb128(0)
+        serializer.serialize_bytes(self.signature)
+        serializer.serialize_bytes(self.authenticator_data)
+        serializer.serialize_bytes(self.client_data_json)
+
+    @staticmethod
+    def deserialize(deserializer: Deserializer) -> "WebAuthnSignature":
+        variant_id = deserializer.deserialize_uleb128_as_u32()
+        if variant_id != 0:
+            raise ValueError(f"Invalid id for WebAuthnSignature: {variant_id}")
+        signature = deserializer.deserialize_bytes()
+        authenticator_data = deserializer.deserialize_bytes()
+        client_data_json = deserializer.deserialize_bytes()
+        return WebAuthnSignature(signature, authenticator_data, client_data_json)
+
+
+# == MultiEd25519 ================================================================
+
+
+class MultiEd25519PublicKey:
+    MAX_KEYS = 32
+    MIN_KEYS = 2
+    MIN_THRESHOLD = 1
+
+    def __init__(self, public_keys: list[Ed25519PublicKey], threshold: int) -> None:
+        if not (self.MIN_KEYS <= len(public_keys) <= self.MAX_KEYS):
+            raise ValueError(
+                f"Must have between {self.MIN_KEYS} and {self.MAX_KEYS} public keys"
+            )
+        if not (self.MIN_THRESHOLD <= threshold <= len(public_keys)):
+            raise ValueError(f"Threshold must be between {self.MIN_THRESHOLD} and {len(public_keys)}")
+        self.public_keys = public_keys
+        self.threshold = threshold
+
+    def to_bytes_inner(self) -> bytes:
+        out = bytearray()
+        for k in self.public_keys:
+            out += k.key
+        out.append(self.threshold)
+        return bytes(out)
+
+    def serialize(self, serializer: Serializer) -> None:
+        serializer.serialize_bytes(self.to_bytes_inner())
+
+    @staticmethod
+    def deserialize(deserializer: Deserializer) -> "MultiEd25519PublicKey":
+        data = deserializer.deserialize_bytes()
+        threshold = data[-1]
+        keys: list[Ed25519PublicKey] = []
+        i = 0
+        while i < len(data) - 1:
+            keys.append(Ed25519PublicKey(data[i : i + Ed25519PublicKey.LENGTH]))
+            i += Ed25519PublicKey.LENGTH
+        return MultiEd25519PublicKey(keys, threshold)
+
+
+class MultiEd25519Signature:
+    def __init__(self, signatures: list[Ed25519Signature], bitmap: bytes) -> None:
+        self.signatures = signatures
+        self.bitmap = bitmap
+
+    def to_bytes_inner(self) -> bytes:
+        out = bytearray()
+        for s in self.signatures:
+            out += s.data
+        out += self.bitmap
+        return bytes(out)
+
+    def serialize(self, serializer: Serializer) -> None:
+        serializer.serialize_bytes(self.to_bytes_inner())
+
+    @staticmethod
+    def deserialize(deserializer: Deserializer) -> "MultiEd25519Signature":
+        data = deserializer.deserialize_bytes()
+        bitmap = data[-4:]
+        signatures: list[Ed25519Signature] = []
+        i = 0
+        end = len(data) - len(bitmap)
+        while i < end:
+            signatures.append(Ed25519Signature(data[i : i + Ed25519Signature.LENGTH]))
+            i += Ed25519Signature.LENGTH
+        return MultiEd25519Signature(signatures, bitmap)
+
+
+# == Ephemeral (used inside Keyless) ============================================
+
+
+class EphemeralPublicKey:
+    """Only Ed25519 variant exists today (EphemeralPublicKeyVariant.Ed25519 = 0)."""
+
+    VARIANT_ED25519 = 0
+
+    def __init__(self, public_key: Ed25519PublicKey) -> None:
+        if not isinstance(public_key, Ed25519PublicKey):
+            raise ValueError(f"Unsupported key for EphemeralPublicKey - {type(public_key)}")
+        self.public_key = public_key
+        self.variant = self.VARIANT_ED25519
+
+    def serialize(self, serializer: Serializer) -> None:
+        serializer.serialize_u32_as_uleb128(self.VARIANT_ED25519)
+        self.public_key.serialize(serializer)
+
+    @staticmethod
+    def deserialize(deserializer: Deserializer) -> "EphemeralPublicKey":
+        index = deserializer.deserialize_uleb128_as_u32()
+        if index == EphemeralPublicKey.VARIANT_ED25519:
+            return EphemeralPublicKey(Ed25519PublicKey.deserialize(deserializer))
+        raise ValueError(f"Unknown variant index for EphemeralPublicKey: {index}")
+
+
+class EphemeralSignature:
+    VARIANT_ED25519 = 0
+
+    def __init__(self, signature: Ed25519Signature) -> None:
+        if not isinstance(signature, Ed25519Signature):
+            raise ValueError(f"Unsupported signature for EphemeralSignature - {type(signature)}")
+        self.signature = signature
+
+    def serialize(self, serializer: Serializer) -> None:
+        serializer.serialize_u32_as_uleb128(self.VARIANT_ED25519)
+        self.signature.serialize(serializer)
+
+    @staticmethod
+    def deserialize(deserializer: Deserializer) -> "EphemeralSignature":
+        index = deserializer.deserialize_uleb128_as_u32()
+        if index == EphemeralSignature.VARIANT_ED25519:
+            return EphemeralSignature(Ed25519Signature.deserialize(deserializer))
+        raise ValueError(f"Unknown variant index for EphemeralSignature: {index}")