[Feat] Add route quotes and complete first-swap funding flow

Author: iamalwaysuncomfortable

shield-swap-sdk/AGENTS.md

@@ -222,12 +222,8 @@ them):
   input records** — `swap_many` implements the recipe; copy it, don't
   improvise.
 
-Suggested path for a new integrator: (1) `onboard()` a profile — it
-doubles as a test fixture; (2) walk swap → `collect_all()` once with the
-Tier 1 methods so the mechanics are concrete; (3) read the reference below
-for the surface your app needs; (4) `tests/integration/` and
-`scripts/rehearsal.py` in the repo are working reference implementations
-of the full journey.
+For the funding, swap, and claim flow, see
+`examples/first-swap/`.
 
 Every write method returns a prepared `DexCall`: nothing touches the
 network until a terminal method — `.simulate()` (local, free),
@@ -405,48 +401,54 @@ exhausting it raises — the fail-fast for a systematically wrong program.
 
 ### Chain methods
 
-### `swap(self, *, pool_key: 'str', token_in_id: 'str', amount_in: 'int | str | Decimal', slippage_bps: 'int' = 50, expected_out: 'Optional[int | str | Decimal]' = None, sqrt_price_limit: 'Optional[int]' = None, deadline_offset_blocks: 'int' = 10000, nonce: 'Optional[int]' = None, identity: 'Optional[BlindedIdentity]' = None, token_in_program: 'Optional[str]' = None, token_record: 'Optional[str]' = None, record_wait_seconds: 'float' = 0.0, wrapper_proofs: 'Optional[str]' = None, track: 'bool' = True, imports: 'Optional[dict[str, str]]' = None, account: 'Any' = None) -> 'DexCall[SwapHandle]'`
+### `confirm_airdrop(self, *, timeout: 'float' = 600.0, poll_interval: 'float' = 5.0, account: 'Any' = None) -> 'ConfirmAirdropResult'`
 
-Prepare one private swap; submit with ``transact()`` or ``delegate()``.
+Fund the account and wait for its airdrop records to become spendable.
 
-Integer ``amount_in`` and ``expected_out`` values are base units.
-Strings and ``Decimal`` values are token units (``"1.5"`` means 1.5
-tokens), converted exactly with registry metadata. Floats, excess
-precision, non-finite values, and amounts outside u128 are rejected.
-Returned handle amounts remain in base units.
+Requires API authentication and scanner registration. ``timeout`` covers
+faucet settlement and scanning. Check ``success`` and ``error`` before
+swapping. A record timeout retains the transfer results; inspect those
+transactions before requesting another airdrop. Scanner errors propagate.
 
-Quote with ``api.get_route`` and pass ``expected_out``. Without a quote,
-the spot estimate ignores fees and price impact. Wrapped inputs use
-underlying token records and route through the swap router automatically.
-``record_wait_seconds`` waits for a covering record (default 0);
-``token_record`` bypasses scanning. Provider errors propagate.
+### `quote(self, *, token_in: 'str', token_out: 'str', amount_in: 'str | Decimal', slippage_bps: 'int' = 50) -> 'SwapQuote'`
 
-Preparing a call reserves a blinding counter when a journal is attached,
-even if the call is discarded or only simulated. The journal retains the
-handle after submission. Without a journal, retain the returned handle
-for claiming and avoid concurrent swaps: chain probing cannot reserve
-counters atomically. ``identity`` supplies an explicit identity;
-``track=False`` bypasses journal reservation.
+Quote a direct or multi-hop swap from two symbols and a token amount.
 
-``deadline_offset_blocks`` defaults to 10,000 (~8 hours at 3s/block)
-to allow delegated proving; an expired deadline rejects at finalize.
+Returns the API's best route and final slippage floor; pass it to
+``swap(quote)``. Requires API authentication. Quoting spends no funds
+and needs no record scanning or transaction signature.
 
-### `claim_swap_output(self, handle: 'SwapHandle', *, wrapper_proofs: 'Optional[str]' = None, imports: 'Optional[dict[str, str]]' = None, account: 'Any' = None) -> 'DexCall[ClaimResult]'`
+### `swap(self, quote: 'Optional[SwapQuote]' = None, *, pool_key: 'Optional[str]' = None, token_in_id: 'Optional[str]' = None, amount_in: 'Optional[int | str | Decimal]' = None, slippage_bps: 'Optional[int]' = None, expected_out: 'Optional[int | str | Decimal]' = None, sqrt_price_limit: 'Optional[int]' = None, deadline_offset_blocks: 'int' = 10000, nonce: 'Optional[int]' = None, identity: 'Optional[BlindedIdentity]' = None, token_in_program: 'Optional[str]' = None, token_record: 'Optional[str]' = None, wrapper_proofs: 'Optional[str]' = None, track: 'bool' = True, imports: 'Optional[dict[str, str]]' = None, account: 'Any' = None) -> 'DexCall[SwapHandle]'`
 
-Claim a private swap's output — phase two of the lifecycle.
+Prepare a direct or multi-hop swap; submit with transact/delegate.
+
+Pass a ``SwapQuote`` to execute its full route and final slippage floor.
+Alternatively pass pool_key, token_in_id, and amount_in for one pool;
+trade parameters cannot override a quote. Legacy strings/Decimal use
+token units, integers base units. Returned handle amounts are base units.
+
+Wrapped inputs spend underlying records. ``token_record`` bypasses scanning.
+Journaled calls reserve a counter during preparation and retain the
+submitted handle. Without a journal, save the handle and avoid concurrent
+swaps; use an explicit identity for concurrency. ``track=False`` bypasses
+journaling. ``deadline_offset_blocks`` defaults to 10,000 (~8 hours).
+
+### `claim_swap_output(self, handle: 'SwapHandle', *, timeout: 'float' = 0.0, wrapper_proofs: 'Optional[str]' = None, imports: 'Optional[dict[str, str]]' = None, account: 'Any' = None) -> 'DexCall[ClaimResult]'`
+
+Claim a private swap's output.
+
+With a journal, ``delegate(wait=True)`` or ``transact(wait=True)``
+records the confirmed claim automatically.
 
 Reads the chain-computed result from ``swap_outputs`` (never an
 off-chain service — these amounts gate money movement), proves
-ownership of the blinded identity, and claims.  A wrapped output or
-refund routes automatically through the router, which unwraps to
-the signer in the same transaction — even for swaps that started
-as direct core calls.  The output and any refund arrive as private
-records owned by the signer (output first, refund second); the
-mapping entry is consumed.
-
-Raises :class:`SwapOutputNotFinalizedError` **at prepare time** when
-the output is not readable yet (retry after a few blocks) or was
-already claimed.
+ownership of the blinded identity, and claims. Wrapped tokens unwrap
+automatically. Output and refunds arrive as private records owned by
+the signer; claiming consumes the mapping entry.
+
+After swap confirmation, ``timeout`` sets the maximum wait in seconds
+(default 0). Missing output is polled every 2s without submitting. Timeout raises
+``SwapOutputNotFinalizedError``; other errors propagate.
 
 ### `create_pool(self, *, token0_id: 'str', token1_id: 'str', fee: 'int', initial_tick: 'int', tick_spacing: 'Optional[int]' = None, initial_sqrt_price: 'Optional[int]' = None, imports: 'Optional[dict[str, str]]' = None, account: 'Any' = None) -> 'DexCall[TxResult]'`
 

shield-swap-sdk/codegen/gen_context.py

@@ -27,7 +27,7 @@
 
 TIER1 = ["from_profile", "onboard", "status", "get_positions",
          "swap_many", "collect_all"]
-TIER2_CLIENT = ["swap", "claim_swap_output", "create_pool", "mint",
+TIER2_CLIENT = ["confirm_airdrop", "quote", "swap", "claim_swap_output", "create_pool", "mint",
                 "increase_liquidity", "decrease_liquidity", "collect", "burn",
                 "plan_rebalance", "rebalance_position",
                 "get_pool", "get_slot", "get_swap_output", "get_swap_execution",
@@ -180,12 +180,8 @@
   input records** — `swap_many` implements the recipe; copy it, don't
   improvise.
 
-Suggested path for a new integrator: (1) `onboard()` a profile — it
-doubles as a test fixture; (2) walk swap → `collect_all()` once with the
-Tier 1 methods so the mechanics are concrete; (3) read the reference below
-for the surface your app needs; (4) `tests/integration/` and
-`scripts/rehearsal.py` in the repo are working reference implementations
-of the full journey."""
+For the funding, swap, and claim flow, see
+`examples/first-swap/`."""
 
 
 def _entry(name: str, fn: object) -> str:

shield-swap-sdk/examples/first-swap/README.md

@@ -36,32 +36,55 @@ query returns HTTP 422, the SDK re-registers the account and retries that query
 once. A failed re-registration surfaces its error.
 
 `dex.api.authenticate()` signs the API challenge with the account's key.
-`confirm_airdrop()` requests tokens and waits for the faucet job to settle.
+`has_swap_balance(source.address, "1.5")` checks for a covering private USDCx
+record first. An account with enough funds skips the airdrop. Scanner errors
+stop the example rather than triggering funding. Otherwise,
+`shield_swap_client.confirm_airdrop()` requests tokens, waits for the faucet
+job to settle, then waits for decrypted, unspent token records from the
+airdrop's transaction IDs. Older records do not satisfy this check.
 It returns `funding.status == "settled"` with per-token outcomes in
 `funding.job.results`, or `"rate_limited"` with the faucet's explanation in
 `funding.message`. A settled job can contain failed token transfers.
-
-The helper polls every 5 seconds and times out after 10 minutes by default.
+The example checks `funding.success` and raises `funding.error` on failure.
+Success requires every transfer accepted and its records available; the error
+includes the rate-limit reason or unsuccessful transfers and their transaction IDs.
+
+The helper polls every 5 seconds; its default 10-minute timeout covers both
+settlement and record scanning. If scanning times out, `funding.success` is
+false and `funding.error` lists the pending transaction IDs. The lower-level
+`api.confirm_airdrop(address)` only waits for faucet settlement.
 `AirdropPendingError.job_id` identifies a timed-out job for further status reads.
-A rate-limited account can continue if it already holds enough USDCx.
-It looks up USDCx and ETH with `get_token(symbol)`, quotes a direct pool
-with `get_route()`, then calls
-`swap(...).delegate(wait=True)` with that quote and a 0.5% slippage limit.
-The example passes `amount_in="1.5"` and the quote's decimal output directly
-to `swap()`. The SDK converts both using token metadata; no unit conversion
-is needed in the example. Strings and `Decimal` values represent token units;
-integers retain their existing base-unit meaning. Excess precision is rejected.
+The example stops on a rate-limit response, missing token results, or any
+transfer that was not accepted on chain. For pending transfers, inspect the
+reported transaction before requesting another airdrop. API errors and
+confirmation timeouts also stop the example before it submits a swap.
+`quote(token_in="USDCx", token_out="ETH", amount_in="1.5", slippage_bps=50)`
+resolves the symbols and asks the API for its best route. The result includes
+`estimated_amount_out`, `minimum_amount_out`, and ordered `hops`. Amounts on the
+quote are decimal strings in token units. The slippage floor applies once to
+the final output, including for two- and three-hop routes.
+
+`swap(quote).delegate(wait=True)` executes that route in one transaction. The
+SDK checks its network, token path, and live pool directions before preparing
+it. A quote reserves no records and does not guarantee its estimated price;
+refresh the quote before a later submission if prices have changed.
+The existing `swap(pool_key=..., token_in_id=..., amount_in=...)` form remains
+available. Its integer amounts use base units; strings/Decimal use token units.
 
 The SDK selects a token record and returns the handle needed to claim.
-One unspent record must cover 1.5 USDCx. The example sets `record_wait_seconds=120` to let the SDK poll for a covering
-record every five seconds. If none appears within two minutes, preparation
-raises `InsufficientRecordsError` before proving or submitting a swap. Scanner
-errors propagate immediately. Other callers default to no wait.
+One unspent record must cover 1.5 USDCx. If the scanner does not return a
+covering record, preparation raises `InsufficientRecordsError` before proving
+or submitting a swap. Allow newly funded records to become available before
+trying again. Scanner errors propagate immediately.
 
 ## Completion and recovery
 
-After the swap confirms, `claim_swap_output(handle).delegate(wait=True)`
-submits one claim and waits for confirmation. `claim.transaction_id` identifies
+After the swap confirms, `claim_swap_output(handle, timeout=5)`
+waits up to five seconds for its output mapping, polling missing-output reads
+every two seconds. Then `.delegate(wait=True)` submits one claim and waits
+for confirmation. Timeout stops before submission; preserve the handle and
+inspect the existing swap instead of rerunning the example. Other read errors
+propagate immediately. `claim.transaction_id` identifies
 the claim and `claim.amount_out` contains the received ETH in base units.
 The example writes no console logs. Generated accounts are saved regardless
 of the journal setting.
@@ -79,7 +102,9 @@ Do not rerun the whole script to recover a swap.
 
 Set `ENABLE_JOURNAL = True` in `swap.py` to attach the SDK's `Journal` at
 `testnet-<account-address>.jsonl` in the working directory. The SDK retains swap
-handles there, and the example records the confirmed claim. Keep the file
+handles there and automatically records the claim after confirmation.
+`delegate(wait=True)` and `transact(wait=True)` update the journal; non-waiting
+submissions do not mark a claim confirmed. Keep the file
 private: it contains the blinding information needed to claim.
 
 The flag only controls journal attachment. It does not change the account,

shield-swap-sdk/examples/first-swap/swap.py

@@ -10,59 +10,61 @@
 
 
 if __name__ == "__main__":
-    # Load a saved account or use an existing private key.
+    ### STEP 1. Create an Aleo Account ###
+    ### Shield Swap runs on the Aleo blockchain to enable private trading of asset pairs.
+    ### This step configures an Aleo account to enable private trading.
+
+    # Use a configured private key or create a new key.
     key = os.environ.get("SHIELD_SWAP_PRIVATE_KEY")
     if not key:
+        # Load a saved private key from an existing Profile or create a new one.
         profile = Profile.load_or_create(network="testnet")
         if profile.network != "testnet":
             raise RuntimeError("This example requires a testnet profile")
         key = profile.private_key
-    private_key = testnet.PrivateKey.from_string(key)
+
+    # Create an Aleo object capable of talking to the Aleo network and configure an account.
     aleo = Aleo(HTTPProvider("https://edge.provable.com/api", network="testnet"))
+    private_key = testnet.PrivateKey.from_string(key)
     account = aleo.account.from_private_key(private_key)
+    address = str(account.address)
+
+    # Register the account with the record scanning service to find its records.
+    # The SDK decrypts the returned records locally.
     registration = aleo.records.register(account)
     if not registration["ok"]:
-        raise RuntimeError(f"Scanner registration failed: {registration['error']}")
-    dex = ShieldSwap(aleo)
-    address = str(account.address)
+        raise RuntimeError(f"Record scanner registration failed: {registration['error']}")
 
-    # Optionally retain this account's swap handles in the SDK journal.
+    ### STEP 2. Create a Shield Swap client and fund the account with testnet tokens. ###
+    # Use this account and scanner for Shield Swap operations and configure a local journal
+    # to keep track of trading activity.
+    shield_swap_client = ShieldSwap(aleo)
     if ENABLE_JOURNAL:
-        dex.journal = Journal(f"testnet-{address}.jsonl")
-
-    # Sign the API challenge with the account's private key.
-    dex.api.authenticate(address, lambda message: str(private_key.sign(message.encode())))
-
-    # Request testnet tokens and wait for the faucet job to settle.
-    funding = dex.api.confirm_airdrop(address)
-
-    # Look up USDCx and ETH, then find a direct pool.
-    source = dex.api.get_token("USDCx")
-    target = dex.api.get_token("ETH")
-    pool = next(pool for pool in dex.api.get_pools()
-                if {pool.token0, pool.token1} == {source.id, target.id})
-
-    # Quote the selected pool in token units.
+        shield_swap_client.journal = Journal(f"testnet-{address}.jsonl")
+    # Authenticate with the shield swap API.
+    shield_swap_client.api.authenticate(address, lambda message: str(private_key.sign(message.encode())))
+    # Use existing private USDCx when one record can cover the swap.
+    source = shield_swap_client.api.get_token("USDCx")
     amount_in = "1.5"
-    quote = dex.api.get_route(
-        token_in=source.id, token_out=target.id, amount_in=amount_in, pool_key=pool.key,
+    if not shield_swap_client.has_swap_balance(source.address, amount_in):
+        # Request testnet tokens and stop if funding fails.
+        funding = shield_swap_client.confirm_airdrop()
+        if not funding.success:
+            raise RuntimeError(funding.error)
+
+    ### STEP 3. Execute a swap between USDCx and ETH. ###
+    # Quote the best available route, including intermediate tokens when useful.
+    # The quote contains the final output estimate and a 0.5% slippage limit.
+    quote = shield_swap_client.quote(
+        token_in="USDCx", token_out="ETH", amount_in=amount_in, slippage_bps=50,
     )
-    if not quote.estimated_amount_out:
-        raise RuntimeError("The selected pool returned no quote")
 
-    # Submit one swap and wait for confirmation. Keep the returned handle for the claim.
-    handle = dex.swap(
-        pool_key=pool.key,
-        token_in_id=source.id,
-        amount_in=amount_in,
-        expected_out=quote.estimated_amount_out,
-        slippage_bps=50,
-        record_wait_seconds=120,
-    ).delegate(wait=True)
+    # Execute the quoted route in one swap transaction and wait for confirmation.
+    handle = shield_swap_client.swap(quote).delegate(wait=True)
 
-    # Claim the confirmed swap's output once using its returned handle.
-    claim = dex.claim_swap_output(handle).delegate(wait=True)
-    if dex.journal is not None:
-        dex.journal.record_claim(handle.swap_id, claim.transaction_id, claim.amount_out)
+    # Wait for the confirmed swap's output to become readable, then submit one claim.
+    claim = shield_swap_client.claim_swap_output(
+        handle, timeout=5,
+    ).delegate(wait=True)
     if claim.amount_out <= 0:
         raise RuntimeError("The claim returned no ETH")