Rebuild Python SDK from Aptos SDK Specification v1.0.0 (Tier 2)

CLAUDE.md

@@ -0,0 +1,117 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is the official Aptos Python SDK for interacting with the Aptos blockchain. It's an async-first SDK supporting Python 3.10+, using Poetry for package management.
+
+## Common Commands
+
+```bash
+# Install dependencies
+poetry install
+
+# Run unit tests (excludes integration tests)
+make test
+
+# Run integration tests (requires live network)
+make integration_test
+
+# Run a single test file
+poetry run pytest tests/test_account.py -v
+
+# Run a single test function
+poetry run pytest tests/test_account.py::TestAccount::test_generate -v
+
+# Run tests with coverage
+make test-coverage
+
+# Format code (autoflake, isort, black)
+make fmt
+
+# Lint and type check (mypy, flake8)
+make lint
+
+# Run examples (requires devnet or localnet)
+make examples
+```
+
+## Architecture
+
+### Core Modules
+
+- **`async_client.py`** - Main entry point: `RestClient`, `FaucetClient`. All I/O is async via httpx HTTP/2.
+- **`transactions.py`** - Transaction building: `RawTransaction`, `EntryFunction`, `Script`, `SignedTransaction`
+- **`transaction_builder.py`** - High-level transaction construction helpers
+- **`account.py`** - Account management with address + private key
+- **`bcs.py`** - Binary Canonical Serialization (Serializer/Deserializer)
+- **`authenticator.py`** - Transaction authenticators (Ed25519, MultiAgent, FeePayer, SingleKey)
+- **`errors.py`** - Spec-aligned error hierarchy (all exceptions inherit from `AptosError`)
+
+### Cryptography Stack
+
+- **`asymmetric_crypto.py`** - Abstract `PrivateKey`/`PublicKey`/`Signature` protocols
+- **`ed25519.py`** - Ed25519 implementation (default)
+- **`secp256k1_ecdsa.py`** - Secp256k1 ECDSA implementation
+- **`crypto_wrapper.py`** - AnyPublicKey/AnySignature and multi-key support
+- **`hashing.py`** - SHA3-256 hashing with domain-separation prefixes
+
+### Network & Configuration
+
+- **`network.py`** - Network enum and configuration (MAINNET, TESTNET, DEVNET, LOCAL)
+- **`chain_id.py`** - Chain ID type
+- **`retry.py`** - Retry configuration for REST client
+- **`mnemonic.py`** - BIP-39 mnemonic support (optional dependency)
+
+### Network Configuration
+
+```python
+from aptos_sdk import Network
+Network.MAINNET  # Production
+Network.TESTNET  # Testing
+Network.DEVNET   # Development
+Network.LOCAL    # Local node (127.0.0.1:8080)
+```
+
+## Key Patterns
+
+### Async Context Manager (Preferred)
+
+```python
+async with RestClient(Network.TESTNET.fullnode_url) as client:
+    balance = await client.account_balance(address)
+```
+
+### Transaction Building
+
+```python
+payload = EntryFunction.natural(
+    "0x1::aptos_account",
+    "transfer",
+    [],  # type args
+    [TransactionArgument(recipient, Serializer.struct),
+     TransactionArgument(amount, Serializer.u64)],
+)
+txn_hash = await client.submit_transaction(account, TransactionPayload(payload))
+await client.wait_for_transaction(txn_hash)
+```
+
+### Error Handling
+
+All SDK exceptions inherit from `AptosError`. Key exceptions: `ApiError`, `NotFoundError`, `BadRequestError`, `RateLimitedError`, `NetworkError`, `CryptoError`, `BcsError`.
+
+## Testing
+
+- Tests use `pytest-asyncio` with `asyncio_mode = "auto"` (no need to mark async tests)
+- Integration test fixtures in `tests/integration/conftest.py` (env-var driven network config)
+- Integration tests marked with `@pytest.mark.integration`
+- `make test` excludes integration tests; `make integration_test` runs them
+- Coverage target: 50% minimum (enforced in CI)
+
+## Code Style
+
+- Line length: 88 (black default)
+- Type hints required throughout
+- Formatting: black + isort (profile="black")
+- All public modules have Apache-2.0 license headers

Makefile

@@ -2,46 +2,25 @@
 # SPDX-License-Identifier: Apache-2.0
 
 test:
-	poetry run python -m unittest discover -s aptos_sdk/ -p '*.py' -t ..
-	poetry run behave
+	poetry run pytest tests/ -v -m "not integration"
 
 test-coverage:
-	poetry run python -m coverage run -m unittest discover -s aptos_sdk/ -p '*.py' -t ..
+	poetry run python -m coverage run -m pytest tests/ -v -m "not integration"
 	poetry run python -m coverage report
 
-test-spec:
-	poetry run behave
+integration_test:
+	poetry run pytest tests/integration/ -v -m integration
 
 fmt:
-	find ./examples ./aptos_sdk ./features . -type f -name "*.py" | xargs poetry run autoflake -i -r --remove-all-unused-imports --remove-unused-variables --ignore-init-module-imports
-	poetry run isort aptos_sdk examples features
-	poetry run black aptos_sdk examples features
+	find ./examples ./aptos_sdk ./tests . -type f -name "*.py" | xargs poetry run autoflake -i -r --remove-all-unused-imports --remove-unused-variables --ignore-init-module-imports
+	poetry run isort aptos_sdk examples tests
+	poetry run black aptos_sdk examples tests
 
 lint:
-	poetry run mypy aptos_sdk examples features
-	poetry run flake8 aptos_sdk examples features
+	poetry run mypy aptos_sdk tests examples
+	poetry run flake8 aptos_sdk tests examples
 
 examples:
-	poetry run python -m examples.aptos_token
-	poetry run python -m examples.fee_payer_transfer_coin
-	poetry run python -m examples.multikey
-	poetry run python -m examples.rotate_key
-	poetry run python -m examples.read_aggregator
-	poetry run python -m examples.secp256k1_ecdsa_transfer_coin
-	poetry run python -m examples.simple_aptos_token
-	poetry run python -m examples.simple_nft
-	poetry run python -m examples.simulate_transfer_coin
 	poetry run python -m examples.transfer_coin
-	poetry run python -m examples.transfer_two_by_two
-
-examples_cli:
-	poetry run python -m examples.hello_blockchain
-	#	poetry run python -m examples.large_package_publisher CURRENTLY BROKEN -- OUT OF GAS
-	#poetry run python -m examples.multisig CURRENTLY BROKEN requires aptos-core checkout
-	poetry run python -m examples.object_code_deployment
-	poetry run python -m examples.your_coin
-
-integration_test:
-	poetry run python -m unittest -b examples.integration_test
 
-.PHONY: examples fmt lint test
+.PHONY: examples fmt integration_test lint test test-coverage

aptos_sdk/__init__.py

@@ -1,2 +1,162 @@
 # Copyright © Aptos Foundation
 # SPDX-License-Identifier: Apache-2.0
+
+"""
+Aptos Python SDK — async-first SDK for the Aptos blockchain.
+
+This is the public API surface.  Import the most commonly used types
+directly from ``aptos_sdk``::
+
+    from aptos_sdk import (
+        Account,
+        AccountAddress,
+        RestClient,
+        FaucetClient,
+        Network,
+    )
+"""
+
+__version__ = "0.12.0"
+
+# Core types
+from .account import Account
+from .account_address import AccountAddress, AuthKeyScheme
+from .asymmetric_crypto import PrivateKeyVariant
+from .async_client import (
+    AccountInfo,
+    FaucetClient,
+    GasEstimate,
+    LedgerInfo,
+    Resource,
+    RestClient,
+    Transaction,
+)
+from .authenticator import AccountAuthenticator, TransactionAuthenticator
+from .bcs import Deserializer, Serializer
+from .chain_id import ChainId
+from .crypto_wrapper import (
+    AnyPublicKey,
+    AnySignature,
+    MultiKeyPublicKey,
+    MultiKeySignature,
+)
+from .ed25519 import (
+    Ed25519PrivateKey,
+    Ed25519PublicKey,
+    Ed25519Signature,
+    MultiEd25519PublicKey,
+    MultiEd25519Signature,
+)
+from .errors import (
+    ApiError,
+    AptosError,
+    AptosTimeoutError,
+    BadRequestError,
+    BcsError,
+    ConflictError,
+    CryptoError,
+    InsufficientBalanceError,
+    InternalServerError,
+    InvalidAddressError,
+    InvalidInputError,
+    InvalidStateError,
+    NetworkError,
+    NotFoundError,
+    ParseError,
+    RateLimitedError,
+    SerializationError,
+    TransactionSubmissionError,
+    VmError,
+)
+from .hashing import HashPrefix, sha3_256
+from .network import Network, NetworkConfig
+from .retry import RetryConfig
+from .secp256k1_ecdsa import Secp256k1PrivateKey, Secp256k1PublicKey, Secp256k1Signature
+from .transaction_builder import TransactionBuilder
+from .transactions import (
+    EntryFunction,
+    FeePayerRawTransaction,
+    ModuleId,
+    MultiAgentRawTransaction,
+    RawTransaction,
+    Script,
+    SignedTransaction,
+    TransactionArgument,
+    TransactionPayload,
+)
+from .type_tag import StructTag, TypeTag
+
+__all__ = [
+    # Core types
+    "AccountAddress",
+    "AuthKeyScheme",
+    "ChainId",
+    "StructTag",
+    "TypeTag",
+    # Errors
+    "AptosError",
+    "AptosTimeoutError",
+    "ApiError",
+    "BadRequestError",
+    "BcsError",
+    "ConflictError",
+    "CryptoError",
+    "InsufficientBalanceError",
+    "InternalServerError",
+    "InvalidAddressError",
+    "InvalidInputError",
+    "InvalidStateError",
+    "NetworkError",
+    "NotFoundError",
+    "ParseError",
+    "RateLimitedError",
+    "SerializationError",
+    "TransactionSubmissionError",
+    "VmError",
+    # BCS
+    "Deserializer",
+    "Serializer",
+    # Hashing
+    "HashPrefix",
+    "sha3_256",
+    # Crypto
+    "PrivateKeyVariant",
+    "Ed25519PrivateKey",
+    "Ed25519PublicKey",
+    "Ed25519Signature",
+    "MultiEd25519PublicKey",
+    "MultiEd25519Signature",
+    "Secp256k1PrivateKey",
+    "Secp256k1PublicKey",
+    "Secp256k1Signature",
+    "AnyPublicKey",
+    "AnySignature",
+    "MultiKeyPublicKey",
+    "MultiKeySignature",
+    # Accounts
+    "Account",
+    # Transactions
+    "EntryFunction",
+    "FeePayerRawTransaction",
+    "ModuleId",
+    "MultiAgentRawTransaction",
+    "RawTransaction",
+    "Script",
+    "SignedTransaction",
+    "TransactionArgument",
+    "TransactionPayload",
+    "AccountAuthenticator",
+    "TransactionAuthenticator",
+    "TransactionBuilder",
+    # Network + Clients
+    "Network",
+    "NetworkConfig",
+    "FaucetClient",
+    "RestClient",
+    "AccountInfo",
+    "GasEstimate",
+    "LedgerInfo",
+    "Resource",
+    "Transaction",
+    "RetryConfig",
+]