Skip to content

MIGRATION-NOTES.md

Latest commit

 

History

History
152 lines (112 loc) · 8.42 KB

MIGRATION-NOTES.md

File metadata and controls

152 lines (112 loc) · 8.42 KB

Migration Notes

A collection of notes to consolidate todos during decoupling efforts (similar doc exists on ts version as well).

API

Generator

  • Currently generated models for KMD have explicit request models resulting in slightly different signatures in contrast with indexer and algod and requiring imports of explicit typed request models specifically on kmd client calls. Do we want to further refine the generation to auto flatten the keys to ensure it does not define an explicit request models or change those models to TypedDicts to reduce the import overhead?

Algod OAS

  • is_frozen field on models in algod is a boolean in the spec but actual returning value is an integer, serde must be updated to handle casting to bool.

KMD

  • algokit-core repo on a branch called feat/account-manager, we had a minor refinement in OAS spec for kmd adding a default value for wallet driver field as well as the generator adjustments to ensure generated model for related endpoint falls back to default 'sqlite' value. Do we want to restore this approach?:

Type annotations

  • Type hints and documentation now refer to the generated algokit_algod_client.AlgodClient (instead of algosdk.v2client.algod.AlgodClient). Update any downstream annotations or typing imports accordingly when migrating to v4.

ABI

  • decoding byte, byte[] and byte[n] now results in a python bytes type instead of list[int]
  • encoding byte now accepts bytes or int types
  • decoding ufixed types now returns a decimal.Decimal instead of an int
  • encoding ufixed types now accepts a decimal.Decimal or an int
  • tuple types decode to tuple instead of list
  • Clarify on whether we are ok with dropping arc32 contracts from type unions in app spec params in app factory and app client

ABI return naming

  • Decide on naming for ABIReturn fields (e.g. value vs return_value, raw_value vs raw_return_value).
  • Current branch aligns with the Rust approach where SDK and ABI variants of ABIReturn are merged into one abstraction; do we keep the same approach in the TS equivalent?

AlgoSDK primitives

  • What do we do with SourceMap abstraction? AlgoSDK version is more feature complete, while we also have a simple autogenerated sourcemap variant in algosdk. ts currently relies on ProgramSourceMap which is vendored from js algosdk. Do we drop the vendored variants completely and enhance api generator to hand roll a custom sourcemap variant we need and rely on that everywhere? Or do we move the vendored source map variant into the algokit-utils and enhance it there?

  • BoxReference used to be a subclass of algosdk BoxReference, now there is a direct equivalent imported from transact package. Do we want to keep aliasing the BoxReference to transact version or do we want to deprecate and advice consumers to import directly from transact?

Contributing Guide

  • Introduce comprehensive contributing guide around running tests/updating snapshots in API client tests and dealing with Polytest

Polytest Integration

This section tracks the generated API endpoint tests from Polytest. Tests are categorized by implementation status.

Algod Client Endpoints

✅ Implemented (21 endpoints)

Endpoint Test File Notes
GET /genesis test_get_genesis.py
GET /health test_get_health.py
GET /ready test_get_ready.py
GET /versions test_get_versions.py
GET /v2/accounts/{address} test_get_v2_accounts_address.py
GET /v2/accounts/{address}/applications/{application-id} test_get_v2_accounts_address_applications_application_id.py
GET /v2/accounts/{address}/assets/{asset-id} test_get_v2_accounts_address_assets_asset_id.py
GET /v2/accounts/{address}/transactions/pending test_get_v2_accounts_address_transactions_pending.py
GET /v2/applications/{application-id} test_get_v2_applications_application_id.py
GET /v2/assets/{asset-id} test_get_v2_assets_asset_id.py
GET /v2/blocks/{round} test_get_v2_blocks_round.py
GET /v2/blocks/{round}/hash test_get_v2_blocks_round_hash.py
GET /v2/blocks/{round}/lightheader/proof test_get_v2_blocks_round_lightheader_proof.py
GET /v2/blocks/{round}/txids test_get_v2_blocks_round_txids.py
GET /v2/deltas/{round} test_get_v2_deltas_round.py
GET /v2/ledger/supply test_get_v2_ledger_supply.py
GET /v2/ledger/sync test_get_v2_ledger_sync.py
GET /v2/status test_get_v2_status.py
GET /v2/status/wait-for-block-after/{round} test_get_v2_status_wait_for_block_after_round.py
GET /v2/transactions/params test_get_v2_transactions_params.py
GET /v2/transactions/pending test_get_v2_transactions_pending.py

⏳ Stub (Not Implemented) (21 endpoints)

Endpoint Test File Notes
DELETE /v2/catchup/{catchpoint} test_delete_v2_catchup_catchpoint.py Admin endpoint
DELETE /v2/ledger/sync test_delete_v2_ledger_sync.py Admin endpoint
GET /v2/applications/{application-id}/box test_get_v2_applications_application_id_box.py
GET /v2/applications/{application-id}/boxes test_get_v2_applications_application_id_boxes.py
GET /v2/blocks/{round}/transactions/{txid}/proof test_get_v2_blocks_round_transactions_txid_proof.py
GET /v2/deltas/{round}/txn/group test_get_v2_deltas_round_txn_group.py
GET /v2/deltas/txn/group/{id} test_get_v2_deltas_txn_group_id.py
GET /v2/devmode/blocks/offset test_get_v2_devmode_blocks_offset.py Dev mode only
GET /v2/experimental test_get_v2_experimental.py
GET /v2/stateproofs/{round} test_get_v2_stateproofs_round.py
GET /v2/transactions/pending/{txid} test_get_v2_transactions_pending_txid.py
POST /v2/catchup/{catchpoint} test_post_v2_catchup_catchpoint.py Admin endpoint
POST /v2/devmode/blocks/offset/{offset} test_post_v2_devmode_blocks_offset_offset.py Dev mode only
POST /v2/ledger/sync/{round} test_post_v2_ledger_sync_round.py Admin endpoint
POST /v2/shutdown test_post_v2_shutdown.py Admin endpoint
POST /v2/teal/compile test_post_v2_teal_compile.py
POST /v2/teal/disassemble test_post_v2_teal_disassemble.py
POST /v2/teal/dryrun test_post_v2_teal_dryrun.py
POST /v2/transactions test_post_v2_transactions.py
POST /v2/transactions/async test_post_v2_transactions_async.py
POST /v2/transactions/simulate test_post_v2_transactions_simulate.py

🔧 Manual Tests (6 tests)

These tests are hand-written to cover complex scenarios not easily generated:

Test File Description
manual/test_block.py Block endpoint against mainnet/testnet with state proof tracking
manual/test_ledger_state_delta.py Ledger state delta endpoint against mainnet/testnet
manual/test_pending_transaction_information.py Pending transaction info flow on localnet
manual/test_raw_transaction.py Raw transaction broadcast on localnet
manual/test_simulate_transactions.py Transaction simulation with trace config
manual/test_suggested_params.py Suggested params and error handling

Indexer Client Endpoints

🔧 Manual Tests (2 tests)

Test File Description
manual/test_search_applications.py Search for applications and app creation flow
manual/test_search_transactions.py Search and lookup transactions

KMD Client Endpoints

🔧 Manual Tests (2 tests)

Test File Description
manual/test_wallet_lifecycle.py Wallet creation and listing
manual/test_key_management.py Key generation and wallet handle management

Test Infrastructure

The Polytest-generated tests use a mock server infrastructure:

  • Mock Server: Docker container running algorandfoundation/algod-mock:latest
  • Parallel Execution: Uses filelock for xdist worker coordination
  • Container Management: Named containers with fixed ports (18000, 18001, 18002)
  • Test Configuration: Located in tests/modules/conftest.py

Summary

Client Implemented Stub Manual Total
Algod 21 21 6 48
Indexer 0 0 2 2
KMD 0 0 2 2
Total 21 21 10 52