Rebuild Python SDK from Aptos SDK Specification v1.0.0 (Tier 2)#74
Open
gregnazario wants to merge 7 commits intomainfrom
Open
Rebuild Python SDK from Aptos SDK Specification v1.0.0 (Tier 2)#74gregnazario wants to merge 7 commits intomainfrom
gregnazario wants to merge 7 commits intomainfrom
Conversation
Ground-up rewrite of the Python SDK based on the Aptos SDK Specification v1.0.0, targeting Tier 2 (P0 + P1) compliance with Python 3.10+. New modules: errors, bcs, hashing, account_address, chain_id, type_tag, asymmetric_crypto, ed25519, secp256k1_ecdsa, crypto_wrapper, account, mnemonic, authenticator, transactions, transaction_builder, network, retry, async_client. Key features: - Async-only API with httpx HTTP/2 client - AIP-40 address formatting, AIP-80 private key formatting - Ed25519 + Secp256k1 ECDSA with SingleKey/MultiKey auth - BIP-39/SLIP-0010 mnemonic key derivation - Fluent TransactionBuilder pattern - Spec-aligned error hierarchy - Retry with exponential backoff + jitter - Full BCS serialization with option/variant_index/map/u256 - Clean mypy, flake8, black across all 19 modules Removes legacy modules: account_sequence_number, aptos_cli_wrapper, aptos_token_client, aptos_tokenv1_client, asymmetric_crypto_wrapper, cli, metadata, package_publisher, transaction_worker.
16 test files covering 698 tests across all SDK modules: - Foundation: errors (hierarchy+categories), bcs (serialize/deserialize round-trips for all types), hashing (SHA3-256, HashPrefix), chain_id - Types: account_address (AIP-40, from_hex/str, BCS), type_tag (all primitive/struct/vector tags, parser, generics) - Crypto: ed25519 (sign/verify, AIP-80, multi-key), secp256k1 (sign/verify, low-S normalization), crypto_wrapper (AnyPublicKey, MultiKey, bitmap) - Accounts: account (generate, persist, mnemonic), mnemonic (BIP-39, SLIP-0010 derivation), network (all configs), retry (backoff, retryable) - Transactions: transactions (RawTransaction sign/verify/BCS, EntryFunction), authenticator (all variant types, BCS), transaction_builder (fluent API) All tests pass with 0 failures. Formatted with black+isort, flake8 clean.
71 tests covering response dataclasses, _raise_for_status error mapping, context manager, all REST endpoints, wait_for_transaction polling, FaucetClient, and legacy compatibility aliases. Total: 769 tests.
Remove unused json and Account imports from test_async_client.py (flake8 F401). Simplify multi-line import in account_address.py.
- Add 22 integration tests across 5 files (transfer, simulate, node queries, fee-payer, secp256k1) with env-var driven network config - Update 6 working examples to use new SDK API surface - Remove 13 broken examples that imported deleted modules - Fix CLAUDE.md to reflect current architecture (Python 3.10+, no IndexerClient, correct module listing and error names) - Extend make lint to cover tests/ and examples/ (mypy + flake8) - Fix mypy errors: implicit Optional, nullable comparisons, async generator return types, sign_transaction typing - Replace legacy typing.List/Tuple with builtin generics in ed25519.py - Add license headers to empty __init__.py files - Add coverage config and integration marker to pyproject.toml
Add 291 new unit tests across 7 test files targeting previously uncovered code paths: - async_client.py: 78% → 100% (account_balance, modules, create/submit transactions, multi-agent, simulation, bcs_transfer, transfer_coins, view_bcs_payload, all legacy aliases) - transactions.py: 79% → 99% (Script, ScriptArgument, Multisig, MultiAgent/FeePayer sign/verify/deserialize, SignedTransaction round-trips) - authenticator.py: 84% → 100% (display methods, deserialization for all authenticator variants, verify paths) - type_tag.py: 89% → 97% (primitive repr/eq, StructTag edge cases, deserialization variants, error paths) - bcs.py: 89% → 95% (overflow/underflow, ULEB128 edge cases, u16/u256, encoder helper, truncated reads) - crypto_wrapper.py: 88% → 97% (display methods, cross-variant rejection, MultiKey boundary cases) - asymmetric_crypto.py: 67% → 77% (parse_hex_input, format_private_key edge cases)
Rewrites the pre-implementation planning document into a post-implementation reference document reflecting the completed Tier 2 SDK rewrite: 19 modules, 11,550 lines, 1,060 tests at 96% coverage. Adds cross-language comparison section, accurate module line counts, corrected test structure, and updated spec compliance matrix with completion status.
There was a problem hiding this comment.
Pull request overview
This PR is a ground-up rewrite of the Aptos Python SDK to fully comply with the Aptos SDK Specification v1.0.0, achieving Tier 2 (P0 + P1) compliance. The SDK now provides comprehensive error handling, improved type safety, async-only operations, and modern Python 3.10+ support with 96% test coverage.
Changes:
- Rebuilt 19 core modules (~11,550 lines) to align with SDK spec v1.0.0
- Added 1,060 unit tests achieving 96% code coverage (up from ~50%)
- Migrated to async-only architecture using httpx with HTTP/2
- Removed legacy modules for token clients, CLI wrappers, and package publishers (moved to separate concerns)
Reviewed changes
Copilot reviewed 41 out of 81 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| examples/multisig.py | Removed legacy multi-signature example (depends on removed modules) |
| examples/multikey.py | Removed multi-key example (depends on removed modules) |
| examples/large_package_publisher.py | Removed package publisher example (module removed) |
| examples/integration_test.py | Simplified to only test fee-payer, secp256k1, simulation, and transfer |
| examples/hello_blockchain.py | Removed hello blockchain example (depends on removed CLI wrapper) |
| examples/fee_payer_transfer_coin.py | Updated to use new API (RestClient constructor, TransactionAuthenticator) |
| examples/common.py | Simplified configuration (removed APTOS_CORE_PATH and INDEXER_URL) |
| examples/aptos_token.py | Removed token client example (module removed) |
| examples/init.py | Added copyright header to empty init file |
| docs/api/index.html | Added redirect to generated API documentation |
| aptos_sdk/transaction_worker.py | Removed transaction worker module (layered concern) |
| aptos_sdk/transaction_builder.py | Added new fluent TransactionBuilder pattern per spec |
| aptos_sdk/retry.py | Added exponential backoff retry strategy per spec |
| aptos_sdk/package_publisher.py | Removed package publisher (layered concern) |
| aptos_sdk/network.py | Added NetworkConfig dataclass and Network constants |
| aptos_sdk/mnemonic.py | Added BIP-39/SLIP-0010 key derivation support |
| aptos_sdk/metadata.py | Removed metadata module (no longer needed) |
| aptos_sdk/hashing.py | Added centralized hashing with domain-separated prefixes |
| aptos_sdk/errors.py | Added 30+ spec-aligned exception types |
| aptos_sdk/crypto_wrapper.py | Added SingleKey/MultiKey wrappers per spec |
| aptos_sdk/cli.py | Removed CLI module (separate tooling concern) |
| aptos_sdk/chain_id.py | Added ChainId type per spec |
| aptos_sdk/bcs.py | Rewrote BCS with improved error handling and protocols |
| aptos_sdk/asymmetric_crypto_wrapper.py | Removed old crypto wrapper (replaced by crypto_wrapper.py) |
| aptos_sdk/asymmetric_crypto.py | Rewrote as protocols with AIP-80 support |
| aptos_sdk/aptos_tokenv1_client.py | Removed token v1 client (layered concern) |
| aptos_sdk/aptos_token_client.py | Removed token client (layered concern) |
| aptos_sdk/aptos_cli_wrapper.py | Removed CLI wrapper (separate tooling concern) |
| aptos_sdk/account_sequence_number.py | Removed sequence number manager (layered concern) |
| aptos_sdk/account.py | Rewrote with BIP-39 support, JSON persistence, and multiple key types |
| aptos_sdk/init.py | Added comprehensive public API exports with version |
| Makefile | Updated test/lint targets to use pytest and new directory structure |
| CLAUDE.md | Added comprehensive project documentation for AI assistants |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Ground-up rewrite of the Aptos Python SDK to fully conform to the Aptos SDK Specification v1.0.0, achieving Tier 2 (P0 + P1) compliance.
What changed
docs/python-DESIGN.mdNew capabilities
Removed modules (layered concerns)
aptos_token_client.py,aptos_tokenv1_client.py— token-specificpackage_publisher.py— can use EntryFunction directlytransaction_worker.py,account_sequence_number.py— can build on coreaptos_cli_wrapper.py,cli.py— separate tooling concernans.py,fungible_asset.py— domain-specific layersBreaking changes
AptosErrorsubtypesAccountAddress.from_str()→from_hex()Network.TESTNETetc.TimeoutError→AptosTimeoutErrorasyncio.run()Quality
aptos_sdk/,tests/,examples/make fmt && make lint && make testModule coverage breakdown
__init__.pyaccount.pyaccount_address.pyasync_client.pyauthenticator.pybcs.pyerrors.pyhashing.pytransaction_builder.pytransactions.pytype_tag.pyTest plan
make test)make lint)make lint)make fmt)make integration_test)make examples)poetry install)