shield-swap-sdk: typed Python client for the shield_swap AMM

[iamalwaysuncomfortable]

What

shield-swap-sdk (new sibling package, shield-swap-sdk/): a typed Python client for shield_swap_v3.aleo, bound to the facade — the Python analog of aleo-viem's @provablehq/shield-swap-sdk. Built on aleo.codegen (#47). Also extends the ABI package (dist now aleo-contract-abi-generator) with an optional imports= parameter (snarkVM validation is contextual; the deployed contract imports test_shield_swap_multisig_core.aleo), and adds deployment + proofless-devnode APIs to the main SDK's bindings.

from aleo import Aleo
from aleo_shield_swap import ShieldSwap

aleo = Aleo(Aleo.HTTPProvider("https://api.provable.com"))
aleo.default_account = account
dex = ShieldSwap(aleo)                       # signer/scanner/proving from the facade

quote = dex.api.get_route(token_in=t0, token_out=t1, amount_in=10**9)
handle = dex.swap(pool_key=key, token_in_id=t0, amount_in=10**9,
                  expected_out=expected).delegate()   # SwapHandle — persist it
out = dex.claim_swap_output(handle).delegate()        # ClaimResult

Surface

• Reads (typed, from committed aleo.codegen bindings): get_pool, get_slot (semantic SlotView: Q64 price(), tick_range()), get_swap_output, is_pool_initialized; pure derive_pool_key/derive_tick_key (BHP256, vector-verified against the TS SDK)
• Writes preserve the facade verb ladder — every verb returns a prepared call (simulate/transact/delegate) with a typed result: swap → claim_swap_output (two-transaction private flow, serializable SwapHandle), create_pool, mint, increase/decrease_liquidity, collect, burn
• Blinded identity: Poseidon8 derivation incl. the 252-bit LE repacking, byte-for-byte against the reference vectors; used_blinded_addresses counter scan
• dex.api: typed REST client for amm-api (generated OpenAPI models; pools/tokens/route/swaps/ohlcv/balances; challenge/verify JWT auth for the gated endpoints), sync + async
• Balances: private (record scan) / public (API) / composed per-token view
• Agent tools + MCP server ([mcp] extra): all 12 verbs with exact JSON schemas
• AsyncShieldSwap: reads, balances, swap lifecycle (liquidity verbs are sync-only for now, documented)
• README in the repo's documentation voice (verb surface, privacy tradeoffs, test tiers)

Renames + versions

Distribution names changed (imports unchanged): main SDK aleo → aleo-sdk (imports as aleo), aleo-abi → aleo-contract-abi-generator (imports as aleo_abi), package dir sdk-shield-swap/ → shield-swap-sdk/ (dist shield-swap-sdk, imports as aleo_shield_swap). All three SDKs are 0.2.0; package_version() falls back to the old aleo dist so existing installs report real versions. READMEs added for shield-swap-sdk and the ABI package.

Main-SDK bindings (sdk/src)

• Process.deploy / Process.deployment_cost — synthesize and price a real deployment (V17: checksum + owner)
• Transaction.from_deployment — deployer signs program ownership over the deployment ID
• Deployment.from_program_unproven — dummy VK + certificate per function/record, mirroring the wasm SDK's buildDevnodeDeploymentTransaction; devnode-only (skips ~14 min of key synthesis for the AMM)
• Execution/Fee.from_authorization_unproven — proofless transactions for devnodes, which skip proof verification

Pinned upstream + drift safety

codegen/regen-abi.sh regenerates the pinned ABI from the deployed program (fetches the import closure; that's the ABI-package change) and re-emits _generated.py; regen-openapi.sh does the API models. A live-tier drift test (check_compatibility(deployed, pinned)) fails our CI on redeploys instead of consumers. The pinned ABI comes from the live deployment — two structs newer than the TS package's snapshot.

Verification

• 79 offline tests (golden vectors for blinding/keys/tick math; verb input orders asserted position-exact against the TS reference; stubs mirror real facade shapes — property outputs, child-first transitions, process registration)
• Live read tier (-m live): 10 passed, 3 skipped (invite-gated route/ohlcv/balances skip with a clear message) — pools/slots against testnet, local pool-key derivation matches the indexer's keys, ABI drift test green against production
• Devnode tier (-m devnode): 9/9 green in ~5 min (ALEO_DEVNODE_UNPROVEN=1) — deploys the vendored stack proofless, then drives pools, liquidity, swaps + claims, collect, and burn end-to-end with mappings asserted at every step; Python analog of the TS devnodeLifecycle.actions.e2e suite
• pyright: 0 errors
• Adversarial review applied; notable catches now regression-tested: snarkVM process registration for dynamic-dispatch token programs, root-transition output scoping, disabled-fee-tier rejection
• Write-tier e2e (-m "live and slow", spends testnet funds) is credential-gated and not yet run — needs ALEO_E2E_PRIVATE_KEY/ALEO_E2E_API_KEY/ALEO_E2E_CONSUMER_ID