feat: migrate shield-swap-sdk to the new shield_swap.aleo stack - #62
Merged
Merged
Conversation
- /auth/verify: send challenge_id from the challenge payload - sessions are httpOnly cookies + X-CSRF-Token (legacy body-JWT kept) - is_authenticated covers both credential kinds - salted retry on DPS consumer-username collisions - lifecycle live test: invite codes are pasted, never generated; shed SHIELD_SWAP_PRIVATE_KEY so the fresh-profile premise holds
…nt under cookie auth - _headers: prefer the live session (csrf + cookies) over Authorization; ss_ tokens don't cover the /access tier and the server reads the header first - 401 while both credentials are loaded drops the expired session and retries as bearer (15-min sessions) - _auth_done recognizes cookie sessions; CSRF never persisted as jwt; from_profile prefers the durable ss_ token over stale session creds
Slot-derived insert hints only validate for a pool's FIRST position — finalize asserts the true linked-list predecessors, so every later mint was rejected on populated pools. find_tick_predecessor walks the ticks mapping from the MIN sentinel (fresh pools anchor at the sentinel; initialized ticks return themselves since validation is skipped).
… 0.3.0 shield-swap-sdk now floors aleo-sdk at 0.3 (Array codegen runtime). Docs updated: staging auth/session + referral-vs-access invites, live- verified LP behaviors (tick-list hints, wrapped-side exact amounts, slippage headroom), sdk-abi example re-pointed at the new stack.
iamalwaysuncomfortable
temporarily deployed
to
pypi-abi
July 28, 2026 21:46 — with 
GitHub Actions
Inactive
GitHub Actions
Inactive
iamalwaysuncomfortable
temporarily deployed
to
pypi
July 28, 2026 21:46 — with
GitHub Actions
Inactive
GitHub Actions
Inactive
iamalwaysuncomfortable
temporarily deployed
to
pypi-shield-swap
July 28, 2026 21:47 — with
GitHub Actions
Inactive
GitHub Actions
Inactive
* docs: voice.md docstrings for the undocumented public surface Adds docstrings to the 206 public classes/methods in sdk/python/aleo and shield-swap-sdk that had none, following .agents/voice.md: present-tense verb lead, side effects named (network / fee / local-only), and each argument, return, and raised error described by consequence. Section syntax follows each file's local idiom rather than one global rule — numpy `Parameters` inside facade/ (54 existing blocks, and voice.md shipped in the same commit as those files), Google `Args:` elsewhere. shield-swap keeps its terser prose voice and its "see :meth:`ApiClient.X`" convention for async mirrors. Where a sync counterpart was already documented the text is mirrored, with async-specific facts corrected: wait_for_transaction_confirmation yields to the event loop via asyncio.sleep, AsyncDexCall.simulate explains why it is not awaited, and three cross-references now point at the async classes instead of RecordScanner / AleoNetworkClient. Three behaviours were checked against the code rather than assumed: get_block_range's end-inclusivity varies by node build (the e2e test says so) so the docstring warns against relying on the last element; decrypt_enabled gates find_credits_record(s), not owned(), which decrypts opportunistically; and codegen's main() exits via argparse on a usage error rather than returning 1. Also removes ApiClient.generate_access_codes and its async mirror. Minting invite/access codes should not be part of the SDK surface. redeem_access_code stays, so a code obtained out-of-band still works, and human-pasted referral invites keep going through redeem_code. Note this reduces SDK surface, not access: POST /access/generate is still reachable directly, and the real gate is the server-side generate right. test_minting_access_codes_is_not_exposed guards the removal. shield-swap-sdk/AGENTS.md is generated from these docstrings, so both copies are regenerated. Four TIER2 entries (api.get_pools, api.get_tokens, derive_pool_key, derive_tick_key) rendered with blank bodies before and now carry real text, which pushed the page past test_gen_context.py's compactness budget — that threshold moves 22k to 24k, with the reason recorded alongside the prior 20k to 22k raise. Verified: 890 passed (sdk, -m "not slow"), 174 passed (shield-swap), pyright strict 0 errors on sdk, gen_context.py --check clean. The 15 pyright errors in shield-swap-sdk are pre-existing and unchanged (confirmed by re-running against HEAD). * fix(facade): exact credits/microcredits conversion (#66) Both directions went through binary floating point and lost value. `credits_to_microcredits` multiplied by 1_000_000 as a float and then truncated toward zero with int(), so ordinary amounts silently underpaid: 1.005 credits became 1_004_999 microcredits, not 1_005_000. Sub-microcredit input was dropped with no error at all (0.9999999 -> 999_999). `microcredits_to_credits` returned a float. Microcredits are a u64, and past 2**53 a float cannot hold the integer — u64 max round-tripped off by one, and 2884 of the first 200_000 microcredit values failed `micro -> credits -> micro` identity. Both now compute in Decimal. Float input is routed through str(), which recovers the shortest representation that round-trips — i.e. the literal the caller wrote — which is what rescues 1.005; str and Decimal input are exact already. Sub-microcredit precision now raises ValueError naming the value, with allow_rounding=True to opt back into truncation, so lost value is an error rather than a silent underpayment. `from_microcredits` returns Decimal instead of float. It still compares equal to the obvious float, so existing assertions hold unchanged, but mixing it into float arithmetic now raises — convert with float() deliberately if you want that, accepting the loss. Scope is contained: these are user-facing convenience helpers only. No internal fee or amount path consumes them (the SDK is integer microcredits end to end), and shield-swap does not use them. Verified: 896 passed (sdk, -m "not slow"; +6 new), pyright strict 0 errors, shield-swap 174 passed and unaffected. * docs: clarify OwnedFilter uuid default wording * docs: drop the self-hosted-scanner recommendation from record docstrings * docs: drop redundant 'Hits the network' notes and the block-range build caveat * docs: make get_pools/get_tokens concrete, name methods instead of 'verbs' * docs(voice): ban "reach for" and vague hedges * docs: drop self-hosted-scanner advice everywhere, keep the view-key disclosure * docs(voice): drop self-hosting from the privacy stance * docs: drop self-hosted-scanner mentions from the READMEs * docs(shield-swap): say "methods", not "verbs" * docs: tighten get_pools, explain why token info can be None * docs: simplify the token-info None explanation * docs(voice): require plain verbs; reword get_tokens decimals note * docs: reword get_swap lag note and get_public_balances * docs: state get_ohlcv's real granularity values and unix-second bounds * docs: explain what the Journal is on the class itself * docs: state that a profile holds one Aleo address * docs: add a Profile create/load usage example
* fix(shield-swap): resolve the DEX API host per network The hard-coded staging host (amm-api-staging.dev.provable.com) now 404s — the deployment moved and shield_swap.aleo is live on mainnet as well as testnet. There are two API hosts now, one per network, so a single module-level constant cannot be right for both. Replaces DEFAULT_API_URL's baked value with SHIELD_SWAP_API_URLS keyed by network and api_url_for(network) to resolve it. ShieldSwap and AsyncShieldSwap now default api_url from their bound client's network_name, so the off-chain indexer always matches the chain being read — a testnet pool key means nothing to the mainnet indexer, and the old default silently guaranteed one of the two was wrong. SHIELD_SWAP_API_URL still overrides every network. An unknown network raises rather than falling back, and the standalone-ApiClient default points at testnet deliberately: an accidental default must not reach mainnet. Verified both hosts serve /tokens and /pools unauthenticated and gate /access/status with 401. 179 passed (shield-swap; +5 new). * fix(shield-swap): walk the tick list on increase_liquidity; OHLCV takes unix seconds Two correctness bugs, both confirmed against the live testnet. increase_liquidity derived its insert hints from pick_insert_hint, which reads slot.next_init_below/above — those bracket the pool's CURRENT tick, not the target. Any bound further out than one initialized tick therefore got a hint above itself, which finalize rejects after the fee is spent. mint already walked the on-chain list (aa71c33); increase_liquidity now does the same via find_tick_predecessor. pick_insert_hint is deleted rather than left in place. It was unused after this change, unexported, untested, and its own docstring conceded it returns hints the contract rejects — a known-wrong helper is a trap. get_ohlcv typed from_ts/to_ts as str, but the API declares from/to as int64 unix seconds (inclusive start, exclusive end). test_api_get_ohlcv passed ISO-8601 strings and failed with 400 "query parameters do not match the expected schema" — it had never run in CI, being live-marked. Both are now int, and the test passes real unix seconds. Verified: 14/14 live reads pass against api.testnet.swap.shield.fi (the OHLCV test was the only red one), 179 shield-swap, 873 sdk, 11 devnode. * chore(shield-swap): regen OpenAPI per-network; pick up UsdcUsdQuote + pool valuation * feat(shield-swap): owned-position views with the contract's view math get_owned_positions(pool_key=?) and get_owned_position(token_id) answer "what do I hold and what is it worth right now" without a transaction. A position spans two sources that neither side can answer alone: the private PositionNFT record carries identity (pool, range, withdrawal) and no amounts; the public positions/slots/ticks mappings carry amounts and no identity. Callers previously had to persist token ids externally and reimplement two pieces of contract math to display a position. position_math.py mirrors the amm-v3 view helpers bit-exactly — amounts_for_liquidity (view_amounts_for_liquidity), fee_growth_inside (get_fee_growth_inside), fee_owed, and u256_wrapping_sub (u256::u256_sub). Fee growth is 256-bit and modular by design: an outside counter may exceed the global one and the difference wraps at 2^256, so every subtraction goes through the wrapping helper — a plain - would raise where the contract wraps. The 17 math vectors are transcribed from the contract's own tests/test_amm_helpers.leo, including the wrap-negative fee_growth_inside cases, so a divergence in either implementation fails the suite rather than silently producing wrong balances. state is None while a mint finalizes (record spendable, mapping not written) and when a boundary tick is uninitialized — the identity stays usable in both cases. Burned positions cannot appear, since burn consumes the record. 196 passed (+27: 17 math vectors, 10 join/filter/lag paths). * feat(shield-swap): swap reserves its blinding counter and journals the handle swap() derived its blinded identity through next_blinded_identity, which scans for the first counter the chain does not carry. Correct in sequence, unsafe in parallel: two swaps starting together read identical chain state, reach the same counter, and the second reverts at finalize once the first consumes it. Nothing surfaces locally — at proving time the address genuinely was unused, because the check and the use are not atomic. swap_many already avoided this by reserving from the journal; single swap() did not. It now takes the same path: reserve one counter under the journal's file lock, derive the identity at it, and record the resulting handle once the broadcast is accepted. Two concurrent swaps can no longer collide. Journaling the handle is the other half. The blinding factor is the only thing that can claim a swap — lose it and the output is unclaimable by anyone, which is the point of blinding it. Recording at accept time (not confirmation) means a crash mid-flight leaves a claimable handle for collect_all(). A journal write that fails after the swap lands raises rather than being swallowed: the swap is already spent, so silently dropping its claim secret is the worse outcome. track=False opts out, an explicit identity= still wins, and without a journal the on-chain probe remains the only option — documented as racing. 206 passed (+5 covering reservation, distinct counters, opt-out, explicit identity, and the journal-less path). * fix(shield-swap): keep pyright clean on the reserved-counter narrowing * fix(shield-swap): the airdrop stage is testnet-only, say so on mainnet The mainnet API publishes neither /airdrop nor /airdrop/{job_id} — verified against both OpenAPI specs — so requesting one there returned 404 and blew up onboard() with a DexApiError. The remedy is the caller funding the account, not a retry, so the stage now raises NotFundedError naming the network and the address. Mainnet onboarding is authenticate -> redeem -> credentials, then the caller funds, then the funded stage passes. * feat(shield-swap): from_profile takes network and endpoint A profile-bound client could only ever be testnet: from_profile called Profile.load_or_create with no arguments, and that defaults network to testnet. With shield_swap.aleo now deployed on mainnet, mainnet was unreachable through the documented entry point. Both apply only when the profile is created — an existing one keeps what it was created with, since its derived pool keys and blinded identities are network-scoped and would not transfer. Give each network its own home. Verified against both live deployments: 5 pools/8 tokens on testnet and 4 pools/8 tokens on mainnet, with locally derived pool keys matching each indexer on both. * fix(shield-swap): the write tier never passed its own credentials conftest gated the write tier on ALEO_E2E_API_KEY / ALEO_E2E_CONSUMER_ID but built its provider without them, so the hosted record scanner answered Unauthorized and every write test failed on the first record read — before reaching the chain. It also never registered the account, which scanning requires. Confirmed by contrast: the same account reads private balances fine when the credentials are wired in (57 credits + test ETH + USDCx on testnet, 0.4 credits + USDCx on mainnet), and fails with exactly this Unauthorized when they are not. The provider now receives both, and the account is registered with the scanner once a key exists. * fix(shield-swap): authenticate the write-tier clients before auth-gated reads get_route is auth-gated; the bespoke clients in test_swap_lifecycle never established a session, so it answered 401 before anything was proved. * fix(shield-swap): quote failures stay errors; expanduser; pyright to zero Four fixes, each a way a wrong value used to reach the chain or the disk. _quote_expected_out swallowed NotAuthenticatedError/NotRedeemedError into a None return, which resolve_swap_params then replaced with a spot estimate. Spot ignores the pool fee, so amount_out_min came out above what the pool can pay: the caller paid for a proof the finalize rejected. "Could not ask" is not "no route" — auth failures now propagate, and swap_many refuses outright when it has no quote and slippage_bps < 10000 rather than proving and broadcasting N swaps engineered to revert. slippage_bps=10000 ("accept any output") still proceeds without one. Profile never called expanduser, so load_or_create("~/x") and SHIELD_SWAP_HOME=~/x each created a literal ~ directory in the cwd and wrote the private key there — where no later run would look for it. Both paths now expand. pyright: 15 errors -> 0. Twelve were real. _lp_programs was annotated str while its own docstring said "None when an explicit record made resolution unnecessary"; the annotation was simply wrong. select_token_record's callers relied on a short-circuit pyright cannot see, so mint and increase now share _fund_side, which resolves record and program together and removes the duplication. authenticate returned self._csrf (str | None) as str. Two dict comprehensions produced list[str | None] despite filtering. The last three were unresolved mcp imports — a declared optional extra, now installed so pyright checks the MCP server rather than skipping it. That surfaced a latent bug in sdk-abi's own stub: _aleo_abi.pyi declared generate_abi with three parameters while the pyo3 signature and the runtime both take four (imports=None). aleo.abi passes four and was correct; the stub was wrong and is now generated from the Rust signature. Bumps all three packages 0.3.1 -> 0.4.0: this branch removes generate_access_codes, replaces DEFAULT_API_URL, and retypes get_ohlcv's timestamps, none of which are patch-compatible. 220 shield-swap, 884 sdk, pyright clean in both packages. * fix(shield-swap): quote the route in canonical amounts, not base units test_private_swap_roundtrip proved, broadcast, and had the network reject at1xze86e… — fee consumed. Diagnosed from the rejected transition's inputs: amount_out_min was 1_844_890_080 while sqrt_price_limit sat at exactly MIN_SQRT_RATIO_X128, the default extreme, so the price bound was not the constraint. The minimum was simply unpayable. Cause, measured against the live API on the ETH/ALEO pool: get_route(amount_in=10000000000000000) -> 1863.544605 (raw base units) get_route(amount_in=0.01) -> 1058.294112 (canonical) /route takes a CANONICAL decimal amount. The test passed raw base units, so the API quoted a trade of 10_000_000 ETH rather than 0.01, returned a price from deep in the book, and the test scaled that into a minimum 76% above what the pool would actually pay. _quote_expected_out was correct throughout — it divides by 10**dec_in before asking and returns 1058294112, matching the canonical quote exactly. The test reimplemented the conversion and got it wrong, so it now calls the helper instead. test_reads_live had the same confusion, passing 10**decimals as amount_in. It never failed because it asserts only shape, but it documented the wrong convention; it now passes "1" with the units spelled out. The write tier now passes for the first time: 2 passed, both roundtrips proved, broadcast, confirmed and claimed against real testnet. * fix(shield-swap): address self-review — async parity, build-time cost, dead code Six findings from reviewing the branch. swap() reserves its counter at BUILD time, not at the terminal method: the blinded address is a transition input, so the identity must exist before anything can be assembled. That means discarding a prepared call — or only calling simulate() — still spends a counter, which contradicts the "nothing happens until a terminal method" contract the README states. The reservation cannot be deferred, so it is documented instead of hidden, with track=False offered as the side-effect-free build. Three tests pin the behaviour rather than leaving it as prose. Async parity: get_owned_positions/get_owned_position now exist on AsyncShieldSwap. sdk/AGENTS.md requires sync+async pairs with shared pure logic, so the PositionNFT record shape moved to _core as POSITION_RECORD_FIELDS + decode_position_record rather than being copied into the second client. test_async_parity fails on any future read method added to one client and not the other, and also fails when its own SYNC_ONLY allowlist goes stale. The async swap docstring pointed at "journal-reserved counters" the async client cannot reserve; it now states that it probes, that the probe races, and that concurrent callers must pass identity explicitly. get_owned_positions read the slot once per position; ten positions in one pool cost ten identical reads. A per-call cache keyed on pool brings that to one, asserted by counting the calls. Record detection keyed on "tick_lower" alone, so any future record type carrying that field would be misread as a position. It now requires the whole field set, with a test using an impostor record that shares one field. amounts_for_liquidity ended in an unreachable `return 0, 0` — its three arms are exhaustive by construction. A silent (0, 0) would read as "holds nothing", so it raises AssertionError instead. amount0_delta divides by both bounds and now documents ZeroDivisionError. The swap docstring renders into AGENTS.md and pushed the page past its compactness budget; it is written tighter rather than raising the cap a third time (23866, 134 spare). 229 shield-swap (+9), 884 sdk, 14 live reads, pyright clean in both. * fix(shield-swap): await the async record scan; both Copilot findings AsyncShieldSwap.get_owned_positions did not await record_provider.find. AsyncRecordsModule.find is `async def`, so `records` was a coroutine and iterating it raised "TypeError: 'coroutine' object is not iterable" — the method could never have worked. Reproduced before fixing. My own parity test missed it because it asserted hasattr, not behaviour: a method that exists and always raises satisfies a presence check. So this adds test_owned_positions_async, which drives the async views against a fake whose find() really is a coroutine — the join, the finalize lag, record filtering, the pool filter, lookup by id, and the empty case. Verified as a real guard by removing the await again: all six fail, and pass once it is restored. Also: test_airdrop_stage_refuses_on_mainnet had its docstring after an assignment, making it a no-op string expression rather than a docstring (ast.get_docstring returned None). Moved to the first statement. Both found by Copilot review; both were real. 235 shield-swap (+6), pyright clean, AGENTS.md current. * fix(shield-swap): swap_many takes expected_out; share the position decoder Two findings from a second review pass. swap_many's refusal message told callers to "quote it yourself and pass expected_out" — and swap_many had no expected_out parameter, so the advice was impossible to follow. It now accepts one, which both makes the message true and gives callers with their own price source (or an unreachable API) a way through. find_position_plaintext matched any dict whose `pool` field equalled the target, so a record of another type carrying that field would be returned as a position and then spent as one. That is the same defect fixed in _owned_from_record last commit; its sibling was left behind. Both now go through decode_position_record, with a test using a lookalike record. The agent page passed its compactness budget again. It had been squeezed to 134 chars of headroom, so the cap moves 24k → 26k deliberately rather than a third squeeze, with the reason recorded alongside the earlier raises. The new paragraph is also written tighter; the page sits at 24130 with 1870 spare. 237 shield-swap (+2), pyright clean.
iamalwaysuncomfortable
deployed
to
pypi-shield-swap
August 6, 2026 05:59 — with
GitHub Actions
Active
GitHub Actions
Active
kpandl
approved these changes
Sep 3, 2026
…tional The DEX API no longer requires an invite: a fresh key has has_access true right after /auth/verify, and POST /access/redeem is marked a compatibility endpoint. Referral codes are the only codes that exist and are optional attribution. - onboarding: the 'redeem' stage becomes 'referral' — skipped without a code or once the account has a referrer; never raises - onboard(referral_code=) replaces onboard(invite_code=) - drop NotRedeemedError, redeem_access_code, and the 403 'invite' mapping - add referral_status() and my_referral_code() to both API clients - agent tools: setup_account takes optional referral_code; redeem_invite becomes redeem_referral_code - OpenAPI spec + models regenerated from the live testnet API - docs, skill, rehearsal, and live tests rewritten for the new model; fix a live test that still expected a body JWT
…l 0.9.0 (#69) Deployed bytecode (both networks) gained claim_swap_output_no_refund, swap_execution_headers/hops, pool_creators; the swap router gained two no-refund claim variants. Testnet additionally has rebalance_position and shield_swap_rebalance_router.aleo (14 entrypoints). The DEX API gained rebalance-state, route topology, referral reporting, richer pool analytics, and machine-readable error codes. Contract - claims dispatch to the no-refund entrypoints when amount_remaining == 0 (sync + async); the refund proof slot is dropped with it - get_swap_execution: header + per-hop fills with lp_fee derived (fee_paid - protocol_fee); get_pool_creator - rebalance: pure planner (rebalance.py, exact-target or budget sizing with the 8-step clamp), plan_rebalance / rebalance_position on the client (route table for all 14 entrypoints, slot rule shared by all, dying-tick hint correction, 20-block deadline), async plan_rebalance - position_math: liquidity_for_amount / liquidity_for_amounts, checked against veil's q128 oracle vectors (now a fixture) - pins: ABIs + bindings regenerated from testnet; rebalance router pinned as a drift guard with a derived input-count parity test; fixtures are the deployed testnet bytecode; devnode harness deploys the router and runs zero-budget and funded rebalances API - 18 new endpoint wrappers on both clients (pool/stats/trades/ticks, session swaps/positions/unclaimed, fee tiers, tick spacings, protocol state, route topology, rebalance state, token list/revoke, referral reporting); get_route(pool_key=) - DexApiError.code/.ref from the error envelope - _build recurses into nested models; a field the API dropped reads None Tooling - agent tools: get_swap_execution, plan_rebalance, rebalance_position - AGENTS.md regenerated (budget 26k -> 32k), README Devnode deployments overpay the base fee by 10%: the bundled snarkVM's deployment_cost undershoots the devnode's consensus by ~2.5%.
There was a problem hiding this comment.
🟡 Changes recommended
Credential URL construction, position selection, array validation, async parity, documentation, and stale lockfile versions must be corrected.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
Migrates Shield Swap to the new shield_swap.aleo stack, adding Q128.128 math, wrapped-token routing, rebalancing, updated onboarding, ABI array support, and expanded integration coverage.
Changes:
- Updates contract bindings, routing, liquidity, claim, and position behavior.
- Adds rebalancing, execution receipts, owned-position views, and referral-based onboarding.
- Extends code generation, tests, documentation, and package versions.
File summaries
| File | Description |
|---|---|
shield-swap-sdk/tests/test_types.py |
Updates Q128 price tests. |
shield-swap-sdk/tests/test_tick_math.py |
Adds X128 vectors and U256 tests. |
shield-swap-sdk/tests/test_swap.py |
Tests routed swaps and journaling. |
shield-swap-sdk/tests/test_swap_many.py |
Tests quote requirements. |
shield-swap-sdk/tests/test_routing.py |
Covers router dispatch tables. |
shield-swap-sdk/tests/test_profile.py |
Tests home-path expansion. |
shield-swap-sdk/tests/test_package.py |
Updates exports and version. |
shield-swap-sdk/tests/test_owned_positions.py |
Tests owned-position joins. |
shield-swap-sdk/tests/test_owned_positions_async.py |
Tests async position views. |
shield-swap-sdk/tests/test_live_api.py |
Updates live API authentication tests. |
shield-swap-sdk/tests/test_lifecycle.py |
Tests referral onboarding and mainnet handling. |
shield-swap-sdk/tests/test_journal.py |
Updates program identifiers. |
shield-swap-sdk/tests/test_generated.py |
Tests regenerated ABI models. |
shield-swap-sdk/tests/test_gen_context.py |
Expands generated agent-guide checks. |
shield-swap-sdk/tests/test_errors.py |
Removes invite-gate errors. |
shield-swap-sdk/tests/test_core.py |
Tests raw amounts, proofs, and records. |
shield-swap-sdk/tests/test_collect_all.py |
Updates raw owed amounts. |
shield-swap-sdk/tests/test_client_reads.py |
Adds execution receipt reads. |
shield-swap-sdk/tests/test_claim.py |
Tests routed and no-refund claims. |
shield-swap-sdk/tests/test_blinding.py |
Adds new-program vectors. |
shield-swap-sdk/tests/test_async_parity.py |
Checks sync/async surface parity. |
shield-swap-sdk/tests/test_api_models.py |
Updates token registry fields. |
shield-swap-sdk/tests/test_agent.py |
Adds referral and rebalance tools. |
shield-swap-sdk/tests/integration/test_swap_lifecycle.py |
Tests plain and wrapped live swaps. |
shield-swap-sdk/tests/integration/test_reads_live.py |
Updates live invariants and API reads. |
shield-swap-sdk/tests/integration/test_drift.py |
Checks deployed router ABIs. |
shield-swap-sdk/tests/integration/test_devnode_lifecycle.py |
Expands devnode lifecycle coverage. |
shield-swap-sdk/tests/integration/test_agent_lifecycle_live.py |
Updates live agent onboarding. |
shield-swap-sdk/tests/integration/devnode_amm.py |
Deploys the new devnode stack. |
shield-swap-sdk/tests/integration/conftest.py |
Wires provider credentials. |
shield-swap-sdk/tests/fixtures/programs/shield_swap_multisig_core.aleo |
Updates multisig program identity. |
shield-swap-sdk/tests/fixtures/programs/shield_swap_freezelist.aleo |
Adds freezelist fixture. |
shield-swap-sdk/tests/conftest.py |
Updates generated fixtures and stubs. |
shield-swap-sdk/scripts/rehearsal.py |
Updates end-to-end rehearsal flow. |
shield-swap-sdk/README.md |
Documents the migrated API. |
shield-swap-sdk/python/aleo_shield_swap/tick_math.py |
Implements Q128.128 math. |
shield-swap-sdk/python/aleo_shield_swap/tick_hints.py |
Removes obsolete hint logic. |
shield-swap-sdk/python/aleo_shield_swap/skills/SKILL.md |
Updates skill terminology. |
shield-swap-sdk/python/aleo_shield_swap/profile.py |
Expands paths and documentation. |
shield-swap-sdk/python/aleo_shield_swap/mcp.py |
Updates MCP documentation. |
shield-swap-sdk/python/aleo_shield_swap/lifecycle.py |
Implements referral onboarding. |
shield-swap-sdk/python/aleo_shield_swap/journal.py |
Expands journal documentation. |
shield-swap-sdk/python/aleo_shield_swap/errors.py |
Updates API error handling. |
shield-swap-sdk/python/aleo_shield_swap/derivations.py |
Changes the default program. |
shield-swap-sdk/python/aleo_shield_swap/agent.py |
Adds execution and rebalance tools. |
shield-swap-sdk/python/aleo_shield_swap/_routing.py |
Adds routing decisions. |
shield-swap-sdk/python/aleo_shield_swap/_calls.py |
Updates call terminology. |
shield-swap-sdk/python/aleo_shield_swap/__init__.py |
Exports new public types. |
shield-swap-sdk/pyproject.toml |
Updates dependencies and version. |
shield-swap-sdk/codegen/regen-openapi.sh |
Updates OpenAPI hosts. |
shield-swap-sdk/codegen/regen-abi.sh |
Regenerates core and router ABIs. |
shield-swap-sdk/codegen/gen_context.py |
Expands generated guidance. |
sdk/Readme.md |
Clarifies record-provider customization. |
sdk/python/tests/test_proving.py |
Clarifies proving endpoint behavior. |
sdk/python/tests/test_facade_client.py |
Adds exact unit-conversion tests. |
sdk/python/tests/test_codegen_runtime.py |
Tests fixed arrays. |
sdk/python/tests/test_codegen_emit.py |
Tests generated array structures. |
sdk/python/aleo/testing/devnode.py |
Expands devnode documentation. |
sdk/python/aleo/record_scanner.py |
Documents scanner configuration. |
sdk/python/aleo/facade/records.py |
Clarifies scanner privacy controls. |
sdk/python/aleo/facade/client.py |
Adds exact microcredit conversions. |
sdk/python/aleo/encryptor.py |
Adds module documentation. |
sdk/python/aleo/codegen/runtime.py |
Adds fixed-array formatting. |
sdk/python/aleo/codegen/_emit.py |
Adds array code generation. |
sdk/python/aleo/codegen/__main__.py |
Documents the codegen CLI. |
sdk/python/aleo/async_record_scanner.py |
Documents async scanner configuration. |
sdk/python/aleo/_scanner_common.py |
Documents scanner filter types. |
sdk/python/aleo/_facade_common.py |
Implements exact credit conversion. |
sdk/python/aleo/_client_common.py |
Expands helper documentation. |
sdk/pyproject.toml |
Bumps SDK version. |
sdk/Cargo.toml |
Bumps Rust package version. |
sdk/Cargo.lock |
Updates package lock metadata. |
sdk/benchmarks/bench_proving.py |
Updates benchmark program names. |
sdk-abi/README.md |
Updates ABI generation example. |
sdk-abi/python/aleo_abi/_aleo_abi.pyi |
Adds imported-program typing. |
sdk-abi/pyproject.toml |
Bumps ABI package version. |
sdk-abi/Cargo.toml |
Bumps ABI crate version. |
sdk-abi/Cargo.lock |
Updates ABI lock metadata. |
README.md |
Updates top-level Shield Swap guidance. |
.claude/skills/shield-swap/SKILL.md |
Updates bundled skill guidance. |
.agents/voice.md |
Adds documentation voice rules. |
Review details
- Files reviewed: 66/110 changed files
- Comments generated: 4
- Review effort level: Balanced
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
…the session, compliance, depth, and referral surface The API retired sixteen routes on 2026-09-08 (veil #144, amm-v3-monorepo#574); the committed OpenAPI spec was a week stale and seven ApiClient wrappers 404'd live on both networks. Regenerate the spec and models and mirror veil: - Drop access_status, my_referral_codes, get_tick_spacings, get_swaps, get_swap, get_position, get_public_balances from both clients. The access flag and the session liveness probe now ride on referral_status(); swap and position detail are chain reads; fee tiers carry their tick spacing. - Public balances are chain reads: ShieldSwap.get_public_balances(programs, address=) reads each token program's `balances` mapping (plain-address key, uN literal, absent = 0). get_balances() takes public from the AMM token program and private records from the underlying program, as veil does. - Wrap the routes that were missing: cookie-session management (get_session, refresh_session adopting the rotated CSRF, list_sessions, revoke_session, logout, logout_all, get_ws_ticket), the compliance reads, batch pool stats, liquidity distribution, and referral issuance (settings, codes, generate) with a new _put helper. /auth/logout needs x-shield-session-id and x-shield-wallet-address binding headers whenever the refresh cookie rides. - position_math: mul_div, liquidity_for_amount0/1 are public, documented. Also lands the live write-tier lessons from 2026-09-03: blinded-identity reservation gallops past counters already used on chain and verifies each one (find_unused_counter, Journal.skip_counters_through); quotes used for amount_out_min are pinned to the traded pool; the live conftest provisions scanner credentials on the provider; new live suites for the API surface, balances, traders, and the full liquidity journey. Swap lifecycle tests size from the largest single record, not the summed balance. Verified: 336 unit tests; live read tier (api 13/16 with 3 environmental skips, reads, balances, traders, drift) and the funded testnet write tier (agent onboarding, swap and liquidity lifecycles, 13/13) all pass.
…olation, typed dict/enum fields, journal catch-up; live suites for async, agent tools, referral posts Medium-effort review of the branch surfaced eight defects; all fixed with regression tests. - The async client's blinded-identity probe was still a fixed 64-counter scan that raised for any account with more history. Both clients now run one galloping search (a generator drives find_unused_counter and find_unused_counter_async), read `used_blinded_addresses` through the node's mapping endpoint instead of downloading the program per swap, and agree on what "used" means via _core.mapping_flag_set. Async swap() takes identity=. - get_public_balances skips (and warns about) a program the network lacks or a non-ARC-20 value instead of failing every token; reads go through aleo.network.get_program_mapping_value. get_balances gained include_private=False and runs the record scan before the public reads, so status()'s public-only fallback repeats nothing and builds no shape of its own. - _coerce builds dict[str, Model] values and Enum fields, so live_compatibility.observed_programs[...] is a LiveProgramObservation and .status a LiveCompatibilityStatus (unknown enum values stay strings). - _reserve_identities: a used counter triggers one gallop from counter+1 and a single counters_skipped event; a journal behind the chain no longer burns counters one reserve-probe-append at a time or logs swap_failed for non-failures. - swap_many's scanner retry no longer sleeps after its last attempt. - Onboarding reclaims this profile's oldest same-name stale API token before falling back to the session at the five-token cap; the server literal the match relies on is documented. - logout() forgets the local cookie session even when it already expired. - The agent get_pools tool read `fee` off the API pool document, which only has fee_percent (basis points); it now emits fee_bps. New live suites: the async clients (API, chain reads cross-checked against the sync client, record reads), the agent tool dispatcher, the referral reporting posts (which take the code this account redeemed, not its own), set_token, and a blinded-identity-vs-chain check. Referral swap-claim tests skip when the account never redeemed a code. Verified: 347 unit tests; live read tier 54/57 (3 environmental skips); opt-in live API 8/8; funded testnet write tier 13/13 on the fixed code.
sdk: snarkvm moves from the git tag v4.8.1 to the crates.io release 4.9.1 (191 upstream commits: ConsensusVersion V18 with credits record translation and a new deployment-cost formula, V19 with per-transaction deployment limits). No FFI API changes were needed. The Process bindings no longer hardcode ConsensusVersion::V17. Both live networks are past their V18 heights and deployment_cost changed at V18, so the literal would have underpriced deployments. execution_cost, deployment_cost, verify_execution and verify_fee now resolve the version from the network's activation table via CONSENSUS_VERSION(height), taking an optional block_height= (default: the newest scheduled version); the type stubs and the proving test cover it. sdk-abi: the four leo crates move to leo master c82f149e (2026-09-09; no release tag pins snarkvm 4.9.1 yet, v4.0.x still pin 4.6.0), and snarkvm to crates.io 4.9.1 with leo's feature set so Process<N>/Program<N> stay the types leo-disassembler expects. That leo fixes a leo-abi bug that emitted record field modes swapped: the test expectation is corrected, and shield-swap's regenerated ABI now reports every record owner as Private, matching the deployed bytecode. Nothing in Python reads record field modes. Verified on the new builds: sdk 884 unit + 4 proving (1 skipped: the venv interpreter's urllib has no CA bundle) + 2 devnode; sdk-abi 8; shield-swap 347 unit, live read tier 54/57 (3 environmental skips), opt-in live API 8/8, devnode lifecycle 12/12, funded testnet write tier 13/13.
… 0.5.0 Breaking for shield-swap-sdk: the 2026-09 DEX API route retirement removed seven ApiClient wrappers and moved balances to chain reads. Lockstep bump for the other two, matching prior releases; both now build on snarkvm 4.9.1.
…n reclaim; batch stats chunking; bulk counter reservation Second review of the branch; six of its eight findings addressed. - sdk facade: a transaction is judged by the rules at its inclusion height, so _authorize_fee (sync and async) passes network.get_latest_height() to execution_cost. The FFI's "newest scheduled version" is documented as the no-node fallback it is, not a default to rely on. - lifecycle: the durable-token name derives from the address, so another machine onboarded with the same key holds the same name and a revoke hits every holder at once. Reclamation now touches only a same-name token idle for TOKEN_IDLE_SECONDS (24h, by last_used_at); a token in recent use is left alone. - lifecycle: at the token cap the credentials stage records the hit and treats it as settled for CAP_RETRY_SECONDS, so repeated onboard() calls stay no-ops instead of re-minting, re-listing and re-registering the scanner every time. Profile.forget_credentials clears the marker once a token is minted. - api: get_pool_stats_batch dedups keys and chunks requests to the route's 100-key cap (POOL_STATS_BATCH_MAX) on both clients. - client: _reserve_identities reserves the batch in one journal event, derives each identity once and skips re-probing a gallop-proved counter. - docs: the AGENTS.md counters paragraph no longer tells agents to feed raw journal.reserve_counters() values to a swap; two stale comments and a dead get_position reference fixed. test_agent_lifecycle_live accepts a mint only once its position is readable on chain — a mint built on a just-spent record confirms as rejected without raising — and retires a dropped attempt from the journal. Verified: sdk 884 unit + proving; shield-swap 351 unit; live read tier 54/57 (3 environmental skips); opt-in live API 8/8; funded testnet write tier 13/13.
The deploy/deployment_cost entries added with the snarkvm 4.9.1 bump referenced a Deployment type the stubs never declared, so CI's strict pyright failed with two undefined-name errors. Mirror the Rust pyclass.
…r URL origin, array length on decode, README host - Write verbs that name a position by token id now select THAT PositionNFT record: find_position_plaintext takes position_token_id and rebalance_position passes it through, so an account with several positions in one pool cannot pair a plan with another position's NFT (a guaranteed revert after the proof is paid for). The agent tool needs no change. - provision_provable_credentials normalizes the endpoint with jwt_origin: a node base such as https://api.provable.com/v2/testnet no longer produces the nonexistent /v2/testnet/consumers. - codegen: decoding enforces the ABI's fixed array length via a new runtime.dec_array, mirroring fmt_array on the encode side; a [field; 16] with 15 siblings is rejected in both directions. shield-swap bindings regenerated. - README: the API host is per network (api.testnet.swap.shield.fi / api.swap.shield.fi), not the retired staging host.
…ted API f85c298 made _authorize_fee pass network.get_latest_height() to execution_cost so estimates use the consensus version in force at the inclusion height. That is right on the hosted Provable API, whose activation schedule is the table compiled into the bindings — and wrong everywhere else: a devnode (or any custom node) runs its own schedule, so mapping its height through the SDK's testnet table priced a devnode at height ~40 under V1 and drained its account ("Fee verification failed: insufficient balance", 3 of 12 devnode lifecycle tests). Off the hosted API the facade now passes None, and the bindings fall back to the newest scheduled version — what such a node runs once past its test heights, and the behaviour before f85c298. Same gate in the async facade. Devnode lifecycle back to 12/12; unit test pins both branches. (cherry picked from commit bef85641ad0e2f9c010bc8622ec43c57ce1d88de)
The edge host is recognised as a hosted-API host only from the edge-default-endpoint change; here the hosted case is the legacy origin.
… required (#70) The hosted Provable API now has an open edge at https://edge.provable.com/api: reads, delegated proving and the hosted record scanner all work with no API key, consumer id or JWT. It becomes DEFAULT_HOST. The credentialed legacy origin https://api.provable.com (LEGACY_HOST) keeps working unchanged with api_key + consumer_id. The edge keeps its services under an /api path prefix, which jwt_origin (scheme + host only) would drop. A new _client_common.service_root(url) keeps the prefix and strips a legacy /v2[/{network}] suffix; both network clients and facade.provider.scanner_base derive {root}/v2/{network}, {root}/prove and {root}/scanner from it. requires_credentials(url) is True only for the legacy host; is_provable_host recognises both. shield-swap: Profile.DEFAULT_ENDPOINT, the MCP server's ALEO_ENDPOINT default and the live-test ENDPOINT default move to the edge. The onboarding credentials stage provisions Provable consumers only when the profile's endpoint requires them; on the edge it just mints the durable DEX token. The live conftest hands out no DPS credentials on the edge. Tests default to the edge and run credential-free there; credential-gated SDK e2e tests skip only when the endpoint actually needs credentials and none are set. Unit tests pin service_root, requires_credentials and the edge URL derivation; the legacy-host derivation tests are unchanged and still pass. Verified on the edge with ALEO_E2E_API_KEY/CONSUMER_ID unset: sdk 892 unit + proving; sdk live e2e 27/27 on testnet and mainnet (delegated transfer, hosted scanner, private roundtrip); shield-swap 355 unit, live read tier 54/57 (3 environmental skips), funded testnet write tier 13/13.
Every read method of AleoNetworkClient and AsyncAleoNetworkClient against the hosted API default (the edge, ALEO_E2E_ENDPOINT overrides), no credentials, with the async answers asserted equal to the sync ones. Two hosted-API gaps surface as skips carrying the status, identical on the edge and the legacy host: /memoryPool/transactions is not served (404) and /statePaths answers 502. The tests pass automatically if either appears.
…e edge The edge is a hosted-API host from this branch on, so the chain head is consulted there too; devnode and custom nodes still get None.
There was a problem hiding this comment.
🟡 Changes recommended
Dependency, async parity, dynamic-import, credential-routing, and public-stub issues remain unresolved.
Get a fresh assessment by requesting another Copilot review.
Review details
- Files reviewed: 63/130 changed files
- Comments generated: 7
- Review effort level: Balanced
Comment on lines
+948
to
+952
| def verify_execution(self, execution: Execution, block_height: int | None = None) -> None: ... | ||
| def verify_fee(self, fee: Fee, deployment_or_execution_id: Field, block_height: int | None = None) -> None: ... | ||
| def execution_cost(self, execution: Execution, block_height: int | None = None) -> tuple[int, tuple[int, int]]: ... | ||
| def deploy(self, program: Program, owner: Address) -> Deployment: ... | ||
| def deployment_cost(self, deployment: Deployment, block_height: int | None = None) -> int: ... |
Member
Author
There was a problem hiding this comment.
Fixed in 9266a8e: __init__.pyi now mirrors the extension stubs — block_height on the four Process methods, deploy, deployment_cost, and the Deployment class.
Comment on lines
+65
to
+69
| def requires_credentials(url: str) -> bool: | ||
| """True if the hosted API at *url* needs api_key/consumer_id for the prover | ||
| and scanner. The edge does not; the legacy ``api.provable.com`` does. | ||
| Off the hosted API there is nothing to authenticate to, so False.""" | ||
| return (urlparse(url).hostname or "").lower() in CREDENTIALED_HOSTS |
Member
Author
There was a problem hiding this comment.
Fixed in 9266a8e: both network clients gate _ensure_jwt on requires_credentials(root), so ambient legacy credentials never produce a /api/jwts call on the edge, and RecordsModule forwards api_key/consumer_id to the scanner only for the credentialed host. Unit tests cover an edge client and an edge scanner configured with legacy credentials.
…sync claim registers both legs, deadline parity, stub mirror, plan amounts as strings - Open edge: ambient legacy api_key/consumer_id no longer trigger a JWT mint at /api/jwts (which does not exist there) — both network clients gate _ensure_jwt on requires_credentials(root), and RecordsModule forwards credentials to the scanner only for the credentialed host. - Async claim registers each leg's token program (wrapper for wrapped legs, the ARC-20 itself for plain ones) before authorization, as the sync client does; the core dispatches into both dynamically. - AsyncShieldSwap.swap defaults deadline_offset_blocks to 10,000 like the sync client (100 was ~5 min and could expire during delegated proving); the parity test now compares shared parameter defaults, not just names. - sdk/python/aleo/__init__.pyi mirrors the extension stubs: block_height on the four Process methods, deploy, deployment_cost and the Deployment class (the dual-stub convention). - shield-swap-sdk requires aleo-sdk>=0.5.0 — _generated.py imports the codegen runtime helpers introduced there. - plan_rebalance / rebalance_position report u128 amounts as strings, as the tool descriptions promise; ticks and ids stay numeric. - README: the async client mirrors the read, swap and claim surface; the liquidity verbs and journal-bound helpers are sync-only for now.
There was a problem hiding this comment.
🔵 Needs a closer look
A brittle live-test assumption and inaccurate public and PR documentation remain unresolved.
Review details
Suppressed comments (1)
Previously missed (1) — in code that hasn't changed since the last review.
shield-swap-sdk/codegen/regen-openapi.sh:11
- The PR description still says the DEX API and regeneration default moved to
amm-api-staging.dev.provable.com, but this script andapi.pynow default to the network-specific production/testnet hosts. Please update the PR description so its stated deployment target matches the code being reviewed.
- Files reviewed: 63/131 changed files
- Comments generated: 0 new
- Review effort level: Balanced
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.
Migrates
shield-swap-sdkfrom the retiredshield_swap_v3.aleoto the freshly deployedshield_swap.aleostack, per the migration guide (amm-v3#62 target). Hard cutover — no state carries over.Contract cutover
PROGRAM_ID = shield_swap.aleo;U256 {hi, lo}prices,MerkleProofstruct,PositionNFT.withdrawal, reshapedPoolState/Slot/Tick/Position/SwapOutput, new compliance records;claim_multi_hop_outputandset_token_decimalsgone._MAGIC_X128tick table +MIN/MAX_SQRT_RATIO_X128pinned from the contract and verified against the reference implementation (f(±400000)matches exactly);u256_to_int/int_to_u256_plaintexthelpers.SlotView.pricere-derived;collect_allrequests exactly the chain-reported owed amounts.mint/claim_swap_output/collectcarry[MerkleProof; 2]arrays — empty-tree defaults while the lists are empty,wrapper_proofs=override for later.mint(withdrawal=…)(defaults to recipient) is stored on the NFT;collectalways pays it — therecipientkwarg is removed.CLAIM_OR_SWAP_DOMAINunchanged in the new bytecode; onlyDEFAULT_PROGRAMflips (v3 vectors kept as algorithm tests, new-program vectors pinned).Automatic router dispatch
Every verb detects each token's wrapped/plain shape (
from_wrapper_token_idchain probe, cached; transport errors propagate rather than misclassifying) and dispatches per the guide's §6 matrix:shield_swap_router.swap_from_wrappedwhen the input is wrapped (funded with underlying records; deposit + burn happen in-transaction;amount_out_min > 0enforced at prepare time)SwapOutputshapes (covers the plain-start/wrapped-claim asymmetry)Record selection understands
credits.aleo(microcredits) and skips recipient-bound wrapper records. Mirrored inAsyncShieldSwap.Supporting changes
fmt_array, toposort/ref-check recursion into array elements).DEFAULT_API_URLand regen default nowhttps://amm-api-staging.dev.provable.com(SHIELD_SWAP_API_URLoverride); models regenerated (wrapper_program→amm_token_program, newunderlying_program/underlying_token_iddrive record-program resolution); redeem no longer rotates the session credential.allow_tokenwith idempotent bootstrap.Verification
shield-swap-sdkunit suite: 171 passed