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.

Author: iamalwaysuncomfortable

shield-swap-sdk/AGENTS.md

@@ -66,7 +66,7 @@ The scan catches positions the journal never saw (account used from
 another machine, journal lost); it needs a registered record
 provider and is skipped silently without one.
 
-### `swap_many(self, *, pool_key: 'str', token_in_id: 'str', amount_in: 'int', count: 'int', slippage_bps: 'int' = 50, record_wait_seconds: 'float' = 120.0, account: 'Any' = None) -> 'SwapBatchReport'`
+### `swap_many(self, *, pool_key: 'str', token_in_id: 'str', amount_in: 'int', count: 'int', slippage_bps: 'int' = 50, expected_out: 'Optional[int]' = None, record_wait_seconds: 'float' = 120.0, account: 'Any' = None) -> 'SwapBatchReport'`
 
 *count* private swaps of *amount_in* each, with reserved counters.
 
@@ -78,6 +78,11 @@ becomes claimable (it stays in ``still_pending``).  A failed
 broadcast burns its counter and the batch continues; failures are
 reported, not raised.  Requires ``from_profile()``.
 
+*expected_out* (base units) skips the route quote.  Without it the batch
+quotes once and refuses rather than falling back to a spot estimate,
+which ignores the pool fee and would revert every swap after paying for
+its proof.
+
 ### `collect_all(self, account: 'Any' = None) -> 'CollectReport'`
 
 Claim every finalized swap and collect owed fees on open positions.

shield-swap-sdk/python/aleo_shield_swap/AGENTS.md

@@ -66,7 +66,7 @@ The scan catches positions the journal never saw (account used from
 another machine, journal lost); it needs a registered record
 provider and is skipped silently without one.
 
-### `swap_many(self, *, pool_key: 'str', token_in_id: 'str', amount_in: 'int', count: 'int', slippage_bps: 'int' = 50, record_wait_seconds: 'float' = 120.0, account: 'Any' = None) -> 'SwapBatchReport'`
+### `swap_many(self, *, pool_key: 'str', token_in_id: 'str', amount_in: 'int', count: 'int', slippage_bps: 'int' = 50, expected_out: 'Optional[int]' = None, record_wait_seconds: 'float' = 120.0, account: 'Any' = None) -> 'SwapBatchReport'`
 
 *count* private swaps of *amount_in* each, with reserved counters.
 
@@ -78,6 +78,11 @@ becomes claimable (it stays in ``still_pending``).  A failed
 broadcast burns its counter and the batch continues; failures are
 reported, not raised.  Requires ``from_profile()``.
 
+*expected_out* (base units) skips the route quote.  Without it the batch
+quotes once and refuses rather than falling back to a spot estimate,
+which ignores the pool fee and would revert every swap after paying for
+its proof.
+
 ### `collect_all(self, account: 'Any' = None) -> 'CollectReport'`
 
 Claim every finalized swap and collect owed fees on open positions.

shield-swap-sdk/python/aleo_shield_swap/_core.py

@@ -188,16 +188,17 @@ def decode_position_record(plaintext: str) -> Optional[dict[str, Any]]:
 
 
 def find_position_plaintext(records: Any, pool_key: str) -> Optional[str]:
-    """First unspent PositionNFT plaintext whose ``pool`` matches, or None."""
+    """First unspent PositionNFT plaintext whose ``pool`` matches, or None.
+
+    Uses :func:`decode_position_record`, so a record of another type that
+    happens to carry a matching ``pool`` field is not returned as a position.
+    """
     for rec in records:
         plaintext = record_plaintext(rec)
         if not plaintext:
             continue
-        try:
-            decoded = parse_plaintext(plaintext)
-        except (ValueError, TypeError):
-            continue
-        if isinstance(decoded, dict) and decoded.get("pool") == pool_key:
+        decoded = decode_position_record(plaintext)
+        if decoded is not None and decoded.get("pool") == pool_key:
             return plaintext
     return None
 

shield-swap-sdk/python/aleo_shield_swap/client.py

@@ -987,6 +987,7 @@ def swap_many(
         amount_in: int,
         count: int,
         slippage_bps: int = 50,
+        expected_out: Optional[int] = None,
         record_wait_seconds: float = 120.0,
         account: Any = None,
     ) -> SwapBatchReport:
@@ -999,18 +1000,25 @@ def swap_many(
         becomes claimable (it stays in ``still_pending``).  A failed
         broadcast burns its counter and the batch continues; failures are
         reported, not raised.  Requires ``from_profile()``.
+
+        *expected_out* (base units) skips the route quote.  Without it the batch
+        quotes once and refuses rather than falling back to a spot estimate,
+        which ignores the pool fee and would revert every swap after paying for
+        its proof.
         """
         if self.journal is None:
             raise ValueError("swap_many() needs a journal — construct with "
                              "ShieldSwap.from_profile().")
         acct = self._account(account)
-        # Quote once for the batch: a spot estimate ignores the pool fee, so
-        # min-out would exceed the real output and finalize would reject.
+        # One quote for the whole batch unless the caller supplied one: a spot
+        # estimate ignores the pool fee, so min-out would exceed the real output
+        # and finalize would reject.
         pool = self.get_pool(pool_key)
         token_out_id = pool.token1 if token_in_id == pool.token0 else pool.token0
-        expected_out = self._quote_expected_out(
-            token_in_id=token_in_id, token_out_id=token_out_id,
-            amount_in=amount_in)
+        if expected_out is None:
+            expected_out = self._quote_expected_out(
+                token_in_id=token_in_id, token_out_id=token_out_id,
+                amount_in=amount_in)
         if expected_out is None and slippage_bps < 10_000:
             # Falling back to the spot estimate would set amount_out_min above
             # what the pool can actually pay (spot ignores the fee), so every

shield-swap-sdk/tests/test_core.py

@@ -178,3 +178,16 @@ def test_extract_tx_id_handles_all_dps_shapes():
                                           "execution": {}}}) == "at1c"
     with pytest.raises(ValueError, match="Cannot find"):
         extract_tx_id({"transaction": {"type": "execute"}})
+
+
+def test_find_position_plaintext_rejects_a_lookalike_record():
+    """A non-PositionNFT record carrying a matching `pool` must not be returned
+    as a position — it would be spent as one."""
+    from aleo_shield_swap._core import find_position_plaintext
+    lookalike = "{ owner: aleo1x.private, pool: 5field.private, amount: 9u128.private }"
+    position = ("{ owner: aleo1x.private, withdrawal: aleo1y.private, "
+                "token_id: 1field.private, token0_id: 2field.private, "
+                "token1_id: 3field.private, pool: 5field.private, "
+                "tick_lower: -60i32.private, tick_upper: 60i32.private }")
+    recs = [{"record_plaintext": lookalike}, {"record_plaintext": position}]
+    assert find_position_plaintext(recs, "5field") == position

shield-swap-sdk/tests/test_gen_context.py

@@ -42,8 +42,11 @@ def test_committed_page_is_current():
 
 
 def test_page_stays_compact():
-    # ~6k tokens — cheap context, enforced.  Raised 20k → 22k with the
+    # ~6.5k tokens — cheap context, enforced.  Raised 20k → 22k with the
     # router-dispatch surface (wrapper_proofs / withdrawal params); 22k → 24k
     # when get_pools/get_tokens/derive_pool_key/derive_tick_key picked up full
-    # docstrings (they rendered blank before).
-    assert len(_render()) < 24_000
+    # docstrings (they rendered blank before); 24k → 26k for the swap/swap_many
+    # footgun warnings (build-time counter reservation, refusing an unusable
+    # quote). 24k had been squeezed to 134 chars of headroom, which any further
+    # edit broke — this is deliberate room, not another squeeze.
+    assert len(_render()) < 26_000

shield-swap-sdk/tests/test_swap_many.py

@@ -210,3 +210,19 @@ def get_route(self, **_):
     with pytest.raises(NotAuthenticatedError):
         fresh._quote_expected_out(token_in_id="t0", token_out_id="t1",
                                   amount_in=10**6)
+
+
+def test_swap_many_accepts_a_caller_supplied_quote(dex, monkeypatch):
+    """expected_out skips the route quote — the escape hatch the refusal
+    message points callers at, so it must actually exist."""
+    called = {"n": 0}
+
+    def _never(self, **kw):
+        called["n"] += 1
+        return None
+
+    monkeypatch.setattr(ShieldSwap, "_quote_expected_out", _never)
+    dex.swap_many(pool_key="5field", token_in_id="t0", amount_in=10**6,
+                  count=1, expected_out=990_000)
+    assert called["n"] == 0, "should not have quoted"
+    assert dex.journal.counter_cursor() == 1