feat: migrate shield-swap-sdk to the new shield_swap.aleo stack - #62
Open
iamalwaysuncomfortable wants to merge 23 commits into
Open
feat: migrate shield-swap-sdk to the new shield_swap.aleo stack#62iamalwaysuncomfortable wants to merge 23 commits into
iamalwaysuncomfortable wants to merge 23 commits into
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
deployed
to
pypi-shield-swap
July 28, 2026 21:47 — with 
GitHub Actions
Active
GitHub Actions
Active
* 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
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
1 participant
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