@eco-incorp/sauce 0.99.5 → 0.99.7

package/actions/dist/spec.js

@@ -1,5 +1,13 @@
 // ---- field kinds ----------------------------------------------------------------------------
 const address = { k: "address" };
+/** A token: a registry symbol or an address. */
+const token = { k: "token" };
+/** A token, or `"native"` for the chain's native currency where the venue takes it. */
+const tokenOrNative = { k: "token", native: true };
+/** A protocol contract: a namespace reference or an address. */
+const contract = { k: "contract" };
+/** A token that is its own contract: a symbol, a namespace reference or an address. */
+const tokenContract = { k: "tokenContract" };
 const recipient = { k: "recipient" };
 const remoteRecipient = { k: "remoteRecipient" };
 const uint256 = { k: "uint", bits: 256 };
@@ -22,92 +30,118 @@ const bridge = spec("bridge", { output: "passThrough" });
 const wrap = spec("wrap", { output: "realized" });
 const stake = spec("stake", { output: "realized" });
 const lending = spec("lending", { output: "passThrough" });
-const token = spec("token", { output: "passThrough" });
+const tokens = spec("token", { output: "passThrough" });
 const source = spec("source", { output: "value" });
+/** Where a pool given by its key is found, said once for every swap that takes one. */
+const BY_KEY = "the program reads it from the factory on chain and reverts if there is none";
 const SPECS = [
-    // -- swaps ----------------------------------------------------------------------------------
-    swap("uniswapV3ExactInput", "Swaps an exact input through one Uniswap V3 pool.", "SwapRouter02.exactInputSingle", {
-        router: f(address, "the SwapRouter02"),
-        tokenIn: f(address, "the token sold"),
-        tokenOut: f(address, "the token bought"),
-        fee: f({ k: "enum", values: [100, 500, 3000, 10000] }, "the pool's fee tier, in hundredths of a bip"),
+    // -- swaps through @sauce/router ------------------------------------------------------------
+    swap("uniswapV2Swap", "Swaps through one Uniswap V2 pair (or a fork's), priced from its reserves and paid by a push.", "@sauce/router uniswapV2: pair.getReserves, an ERC-20 transfer to the pair, pair.swap", {
+        pool: opt(contract, "the pair; or leave it out and give `factory`"),
+        factory: opt(contract, `instead of \`pool\`: a Uniswap V2-style factory ("UniswapV2.Factory"), whose ` +
+            `getPair(tokenIn, tokenOut) is the pair; ${BY_KEY}`),
+        tokenIn: f(token, "the token sold, pushed to the pair"),
+        tokenOut: f(token, "the token bought; the direction is the pair's sort order"),
+        feePpm: opt(int(0, 999_999), "the pair's LP fee in parts per million; absent or 0 is 3000 (0.30%), PancakeSwap V2 is 2500"),
         amountOutMin: MIN_OUT,
-        sqrtPriceLimitX96: opt(uint160, "a price limit; absent or 0 for none"),
         recipient: RECIPIENT,
+    }, { oneOf: [["pool"], ["factory"]] }),
+    swap("uniswapV3Swap", "Swaps through one Uniswap V3 pool (or a fork's), through the Pot's Router, which answers its callback.", "@sauce/router uniswapV3: Router.swapV3", {
+        pool: opt(contract, "the pool; or leave it out and give `factory` with `fee` or `tickSpacing`"),
+        factory: opt(contract, "instead of `pool`: the factory whose getPool(tokenIn, tokenOut, key) is the pool — a " +
+            'Uniswap V3-style factory with `fee` ("UniswapV3.Factory", "PancakeswapV3.Factory"), or ' +
+            `Aerodrome Slipstream's with \`tickSpacing\` ("AerodromeSlipstream.CLFactory"); ${BY_KEY}`),
+        fee: opt(uintN(24), "with `factory`: the pool's fee tier, in hundredths of a bip (500 is 0.05%)"),
+        tickSpacing: opt(int(1, 8_388_607), "with a Slipstream `factory`: the pool's tick spacing"),
+        tokenIn: f(token, "the token sold"),
+        tokenOut: f(token, "the token bought"),
+        sqrtPriceLimitX96: opt(uint160, "a price at which the swap stops, leaving the rest of the input in the Pot; absent or 0 for none"),
+        amountOutMin: MIN_OUT,
+        recipient: RECIPIENT,
+    }, { oneOf: [["pool"], ["factory", "fee"], ["factory", "tickSpacing"]] }),
+    swap("uniswapV4Swap", "Swaps through one Uniswap V4 pool, named by its key, through the Pot's Router, which settles " +
+        "with the PoolManager.", "@sauce/router uniswapV4: Router.swapV4", {
+        poolManager: f(contract, 'the PoolManager ("UniswapV4.PoolManager")'),
+        tokenIn: f(tokenOrNative, 'the token sold; "native" is the native currency'),
+        tokenOut: f(tokenOrNative, 'the token bought; "native" is the native currency'),
+        fee: f(uintN(24), "the pool key's fee, in hundredths of a bip"),
+        tickSpacing: f(int(1, 32767), "the pool key's tick spacing"),
+        hooks: opt(contract, "the pool key's hooks contract; absent for a pool with none"),
+        sqrtPriceLimitX96: opt(uint160, "a price at which the swap stops, leaving the rest of the input in the Pot; absent or 0 for none"),
+        amountOutMin: MIN_OUT,
+        recipient: RECIPIENT,
+    }),
+    swap("curveSwap", "Swaps through a Curve pool's 4-argument `exchange`, approving exactly the input; the output " +
+        "is a balance delta.", "@sauce/router curve: an exact ERC-20 approval, then pool.exchange(int128|uint256 i, j, dx, min_dy)", {
+        pool: f(contract, "the Curve pool"),
+        tokenIn: f(token, "the token sold, approved to the pool for exactly the amount"),
+        tokenOut: f(token, "the token bought, whose balance delta is the output"),
+        i: f(int(0, 7), "the pool index of the coin sold"),
+        j: f(int(0, 7), "the pool index of the coin bought"),
+        indexType: f({ k: "enum", values: ["int128", "uint256"] }, "the pool's index type: int128 for StableSwap and NG pools, uint256 for CryptoSwap"),
+        amountOutMin: MIN_OUT,
+        recipient: f(recipient, `${RECIPIENT.doc}; the pool pays the Pot, which forwards it with a transfer`),
     }),
-    swap("uniswapV3ExactInputMultiHop", "Swaps an exact input along a packed Uniswap V3 path.", "SwapRouter02.exactInput", {
-        router: f(address, "the SwapRouter02"),
-        path: f(bytes, "the packed path: token ++ fee (3 bytes) ++ token ++ …"),
+    swap("balancerV2Swap", "Swaps through one Balancer V2 pool, approving the Vault for exactly the input.", "@sauce/router balancerV2: an exact ERC-20 approval, then Vault.swap (GIVEN_IN)", {
+        vault: f(contract, "the Balancer V2 Vault"),
+        poolId: f(bytes32, "the pool id"),
+        tokenIn: f(token, "the token sold, approved to the Vault for exactly the amount"),
+        tokenOut: f(token, "the token bought"),
         amountOutMin: MIN_OUT,
         recipient: RECIPIENT,
     }),
-    swap("uniswapV4ExactInput", "Swaps an exact ERC-20 input through one Uniswap V4 pool via the Universal Router.", "an ERC-20 transfer to the router, then UniversalRouter.execute (V4_SWAP: swap, settle, take)", {
-        router: f(address, "the Universal Router"),
-        poolKey: f({
-            k: "object",
-            fields: {
-                currency0: f(address, "the pool's lower currency"),
-                currency1: f(address, "the pool's higher currency"),
-                fee: f(uintN(24), "the pool fee, in hundredths of a bip"),
-                tickSpacing: f(int(1, 32767), "the pool's tick spacing"),
-                hooks: f(address, "the pool's hooks contract, or the zero address"),
-            },
-        }, "the V4 pool key"),
-        zeroForOne: f(bool, "true sells currency0 for currency1"),
-        amountOutMin: f(uint128, "the least output accepted; the router reverts below it"),
+    swap("dodoV2Swap", "Swaps through one DODO V2 pool (DVM, DPP or DSP), paid by a push.", "@sauce/router dodoV2: an ERC-20 transfer to the pool, then sellBase(to) or sellQuote(to)", {
+        pool: f(contract, "the pool"),
+        tokenIn: f(token, "the token sold, pushed to the pool"),
+        tokenOut: f(token, "the token bought"),
+        baseToken: f(token, "the pool's base token; tokenIn and tokenOut must be base and quote"),
+        quoteToken: f(token, "the pool's quote token"),
+        amountOutMin: MIN_OUT,
         recipient: RECIPIENT,
     }),
-    swap("uniswapV4ExactInputMultiHop", "Swaps an exact ERC-20 input along a Uniswap V4 path via the Universal Router.", "an ERC-20 transfer to the router, then UniversalRouter.execute (V4_SWAP: swap, settle, take)", {
-        router: f(address, "the Universal Router"),
-        currencyIn: f(address, "the currency sold"),
-        path: f({
-            k: "array",
-            min: 1,
-            of: {
-                k: "object",
-                fields: {
-                    intermediateCurrency: f(address, "the currency this hop buys"),
-                    fee: f(uintN(24), "the hop's pool fee"),
-                    tickSpacing: f(int(1, 32767), "the hop's pool tick spacing"),
-                    hooks: f(address, "the hop's pool hooks, or the zero address"),
-                },
-            },
-        }, "the hops, in order; the last hop's currency is the output"),
-        amountOutMin: f(uint128, "the least output accepted; the router reverts below it"),
+    swap("traderJoeLBSwap", "Swaps through one Trader Joe Liquidity Book pair, paid by a push.", "@sauce/router traderJoeLB: an ERC-20 transfer to the pair, then pair.swap(swapForY, to)", {
+        pool: opt(contract, "the pair; or leave it out and give `factory` with `binStep`"),
+        factory: opt(contract, 'instead of `pool`: the LBFactory ("TraderJoe.LBFactory"), whose ' +
+            `getLBPairInformation(tokenIn, tokenOut, binStep) names the pair; ${BY_KEY}`),
+        binStep: opt(int(1, 65_535), "with `factory`: the pair's bin step"),
+        tokenIn: f(token, "the token sold, pushed to the pair"),
+        tokenOut: f(token, "the token bought"),
+        tokenX: opt(token, "the pair's token X; tokenIn and tokenOut must be X and Y. Leave tokenX and tokenY out " +
+            "to read them from the pair"),
+        tokenY: opt(token, "the pair's token Y"),
+        amountOutMin: MIN_OUT,
+        recipient: RECIPIENT,
+    }, { oneOf: [["pool"], ["factory", "binStep"]], together: [["tokenX", "tokenY"]] }),
+    swap("woofiSwap", "Swaps through WOOFi's WooPPV2, paid by a push.", "@sauce/router woofi: an ERC-20 transfer to the pool, then WooPPV2.swap", {
+        pool: f(contract, "the WooPPV2 itself, not the WooRouterV2"),
+        tokenIn: f(token, "the token sold, pushed to the pool"),
+        tokenOut: f(token, "the token bought"),
+        amountOutMin: f(uint256, "the least output accepted, as the pool's own minToAmount; required and positive, because the pool prices from an oracle"),
         recipient: RECIPIENT,
     }),
-    swap("curveSwap", "Swaps through a Curve pool's 4-argument `exchange`; the output is a balance delta.", "pool.exchange(int128,int128,uint256,uint256)", {
-        pool: f(address, "the Curve pool"),
-        tokenOut: f(address, "the token bought, whose balance delta is the output"),
-        i: f(int(0, 7), "the pool index of the coin sold"),
-        j: f(int(0, 7), "the pool index of the coin bought"),
+    swap("maverickV2Swap", "Swaps through one Maverick V2 pool, through the Pot's Router, which pays what the pool asks for.", "@sauce/router maverickV2: Router.swap", {
+        pool: f(contract, "the pool"),
+        tokenIn: f(token, "the token sold"),
+        tokenOut: f(token, "the token bought"),
         amountOutMin: MIN_OUT,
-        recipient: f(recipient, `${RECIPIENT.doc}; the pool pays the Pot, which forwards it with a transfer`),
+        recipient: RECIPIENT,
     }),
+    // -- swaps at venues @sauce/router does not cover -------------------------------------------
     swap("curveRouterNGSwap", "Swaps along a Curve RouterNG route of up to five hops.", "RouterNG.exchange(address[11],uint256[5][5],uint256,uint256,address[5],address)", {
-        router: f(address, "the Curve RouterNG"),
-        route: f({ k: "array", of: address, min: 1, max: 11 }, "the route; padded to 11 with zero addresses"),
+        router: f(contract, "the Curve RouterNG"),
+        route: f({ k: "array", of: tokenContract, min: 1, max: 11 }, "the route, tokens and pools alternating; padded to 11 with zero addresses"),
         swapParams: f({
             k: "array",
             min: 1,
             max: 5,
             of: { k: "tuple", of: [int(0, 255), int(0, 255), int(0, 255), int(0, 255), int(0, 255)] },
         }, "per hop: [i, j, swap_type, pool_type, n_coins]; padded to 5 rows"),
-        pools: f({ k: "array", of: address, max: 5 }, "a zap pool where a hop needs one; padded to 5"),
+        pools: f({ k: "array", of: contract, max: 5 }, "a zap pool where a hop needs one; padded to 5"),
         amountOutMin: MIN_OUT,
         recipient: RECIPIENT,
     }),
-    swap("balancerV2Swap", "Swaps through one Balancer V2 pool.", "Vault.swap", {
-        vault: f(address, "the Balancer V2 Vault"),
-        poolId: f(bytes32, "the pool id"),
-        tokenIn: f(address, "the token sold"),
-        tokenOut: f(address, "the token bought"),
-        amountOutMin: MIN_OUT,
-        recipient: RECIPIENT,
-        deadline: DEADLINE,
-    }),
     swap("balancerV2BatchSwap", "Swaps along Balancer V2 pools in one batch; the output is a balance delta.", "Vault.batchSwap", {
-        vault: f(address, "the Balancer V2 Vault"),
+        vault: f(contract, "the Balancer V2 Vault"),
         steps: f({
             k: "array",
             min: 1,
@@ -121,32 +155,25 @@ const SPECS = [
                 },
             },
         }, "the batch's steps; the last step's output asset is the output"),
-        assets: f({ k: "array", of: address, min: 2 }, "every asset the steps index"),
+        assets: f({ k: "array", of: tokenOrNative, min: 2 }, 'every asset the steps index; "native" is the native currency'),
         amountOutMin: MIN_OUT,
         recipient: RECIPIENT,
         deadline: DEADLINE,
     }, { spends: false }),
     swap("balancerV3Swap", "Swaps an exact input through one Balancer V3 pool; the router pays the Pot and pulls " +
         "through Permit2.", "Router.swapSingleTokenExactIn", {
-        router: f(address, "the Balancer V3 Router"),
-        pool: f(address, "the pool"),
-        tokenIn: f(address, "the token sold"),
-        tokenOut: f(address, "the token bought"),
+        router: f(contract, "the Balancer V3 Router"),
+        pool: f(contract, "the pool"),
+        tokenIn: f(token, "the token sold"),
+        tokenOut: f(token, "the token bought"),
         amountOutMin: MIN_OUT,
         deadline: DEADLINE,
         wethIsEth: f(bool, "true to pay or receive native ETH for WETH"),
     }),
-    swap("uniswapV2Swap", "Swaps an exact input along a Uniswap V2 path; the output is a balance delta.", "UniswapV2Router.swapExactTokensForTokens", {
-        router: f(address, "the V2 router"),
-        path: f({ k: "array", of: address, min: 2 }, "the token path; the last token is the output"),
-        amountOutMin: MIN_OUT,
-        recipient: RECIPIENT,
-        deadline: DEADLINE,
-    }),
     swap("ambientSwap", "Swaps through an Ambient (CrocSwap) pool; the dex pays the Pot, and the output is a balance delta.", "CrocSwapDex.userCmd(1, abi.encode(...))", {
-        dex: f(address, "the CrocSwapDex"),
-        base: f(address, "the pool's base token (numerically lower)"),
-        quote: f(address, "the pool's quote token"),
+        dex: f(contract, "the CrocSwapDex"),
+        base: f(tokenOrNative, "the pool's base token (numerically lower)"),
+        quote: f(token, "the pool's quote token"),
         poolIdx: f(uintN(53), "the pool type index (420 is the standard pool)"),
         isBuy: f(bool, "true pays base and receives quote"),
         inBaseQty: f(bool, "true when the amount is denominated in the base token"),
@@ -155,33 +182,19 @@ const SPECS = [
         amountOutMin: f(uint128, "the least output accepted; the dex reverts below it"),
         reserveFlags: f(uintN(8), "0x1 settles base from surplus, 0x2 quote"),
     }),
-    swap("dodoSwap", "Swaps through DODO pairs via the DODO proxy, which pays the Pot.", "DODOProxy.dodoSwapV2TokenToToken (or dodoSwapV1)", {
-        proxy: f(address, "the DODO proxy; approvals go to DODOApprove, not to it"),
-        fromToken: f(address, "the token sold"),
-        toToken: f(address, "the token bought"),
-        pairs: f({ k: "array", of: address, min: 1 }, "the pairs to route through"),
+    swap("dodoV1Swap", "Swaps through legacy DODO V1 (Classical) pairs via the DODO proxy, which pays the Pot.", "DODOProxy.dodoSwapV1", {
+        proxy: f(contract, "the DODO proxy; approvals go to DODOApprove, not to it"),
+        tokenIn: f(token, "the token sold"),
+        tokenOut: f(token, "the token bought"),
+        pairs: f({ k: "array", of: contract, min: 1 }, "the V1 pairs to route through"),
         directions: f(uintN(53), "a bit per pair: 0 sells base, 1 sells quote"),
         amountOutMin: MIN_OUT,
         deadline: DEADLINE,
-        version: opt({ k: "enum", values: ["v1", "v2"] }, '"v1" routes legacy Classical pairs through `dodoSwapV1`; default "v2"'),
-    }),
-    swap("maverickSwap", "Swaps an exact input through one Maverick V2 pool.", "MaverickV2Router.exactInputSingle", {
-        router: f(address, "the Maverick V2 router"),
-        pool: f(address, "the pool"),
-        tokenAIn: f(bool, "true sells the pool's token A"),
-        amountOutMin: MIN_OUT,
-        recipient: RECIPIENT,
-    }),
-    swap("maverickMultiHopSwap", "Swaps an exact input along a packed Maverick V2 path.", "MaverickV2Router.exactInputMultiHop", {
-        router: f(address, "the Maverick V2 router"),
-        path: f(bytes, "per hop, the pool's 20 bytes then one byte: 1 sells token A, 0 token B"),
-        amountOutMin: MIN_OUT,
-        recipient: RECIPIENT,
     }),
     swap("carbonSwap", "Trades against Carbon strategies by source amount; the controller pays the Pot.", "CarbonController.tradeBySourceAmount", {
-        controller: f(address, "the CarbonController"),
-        sourceToken: f(address, "the token sold"),
-        targetToken: f(address, "the token bought"),
+        controller: f(contract, "the CarbonController"),
+        sourceToken: f(token, "the token sold"),
+        targetToken: f(token, "the token bought"),
         tradeActions: f({
             k: "array",
             min: 1,
@@ -197,22 +210,22 @@ const SPECS = [
         deadline: DEADLINE,
     }, { spends: false }),
     swap("fraxswapSwap", "Swaps an exact input along a Fraxswap path; the output is a balance delta.", "FraxswapRouter.swapExactTokensForTokens", {
-        router: f(address, "the Fraxswap router"),
-        path: f({ k: "array", of: address, min: 2 }, "the token path; the last token is the output"),
+        router: f(contract, "the Fraxswap router"),
+        path: f({ k: "array", of: token, min: 2 }, "the token path; the last token is the output"),
         amountOutMin: MIN_OUT,
         recipient: RECIPIENT,
         deadline: DEADLINE,
     }),
     swap("fluidDexT1Swap", "Swaps an exact ERC-20 input through a Fluid DEX T1 pool.", "FluidDexT1.swapIn", {
-        pool: f(address, "the pool"),
+        pool: f(contract, "the pool"),
         swap0to1: f(bool, "true sells token0"),
         amountOutMin: MIN_OUT,
         recipient: RECIPIENT,
     }),
     // -- bridges --------------------------------------------------------------------------------
     bridge("acrossBridge", "Deposits into an Across SpokePool for the same token on the destination, less the relayer fee.", "SpokePool.depositV3", {
-        spokePool: f(address, "the origin SpokePool; it pulls the token, so approve it first"),
-        token: f(address, "the token bridged (input and output)"),
+        spokePool: f(contract, "the origin SpokePool; it pulls the token, so approve it first"),
+        token: f(token, "the token bridged (input and output)"),
         destChainId: f(int(1, Number.MAX_SAFE_INTEGER), "the destination chain id"),
         recipient: f(address, "receives on the destination"),
         relayerFee: f(uint256, "kept by the relayer: the destination receives `amount - relayerFee`"),
@@ -222,98 +235,98 @@ const SPECS = [
         message: f(bytes, "delivered with the fill; 0x for none"),
     }),
     bridge("stargateBridge", "Sends through a Stargate V2 ERC-20 pool (taxi), paying the LayerZero fee it quotes.", "StargatePool.quoteSend, then StargatePool.send", {
-        pool: f(address, "the StargatePool; it pulls the token, so approve it first"),
+        pool: f(contract, "the StargatePool; it pulls the token, so approve it first"),
         dstEid: f(uintN(32), "the destination's LayerZero endpoint id"),
         recipient: f(remoteRecipient, "receives on the destination"),
         amountOutMin: f(uint256, "the least the destination may receive"),
     }, { value: "the quoted native fee, from the Pot" }),
     bridge("cctpBridge", "Burns USDC through Circle's CCTP V2 TokenMessenger for minting on the destination.", "TokenMessengerV2.depositForBurn", {
-        tokenMessenger: f(address, "the CCTP V2 TokenMessenger; it pulls the token, so approve it first"),
-        token: f(address, "the burned token (USDC)"),
+        tokenMessenger: f(contract, "the CCTP V2 TokenMessenger; it pulls the token, so approve it first"),
+        token: f(token, "the burned token (USDC)"),
         destinationDomain: f(uintN(32), "the destination's CCTP domain"),
         recipient: f(remoteRecipient, "receives the mint on the destination"),
         maxFee: opt(uint256, 'the most the transfer may pay in fees, from the amount; default "0"'),
         minFinalityThreshold: opt(uintN(32), "2000 waits for finality (standard, the default); 1000 is fast"),
     }),
     bridge("hyperlaneBridge", "Transfers through a Hyperlane ERC-20 warp route, paying the interchain gas it quotes.", "TokenRouter.quoteGasPayment, then TokenRouter.transferRemote", {
-        router: f(address, "the warp route; it pulls the amount plus any fee it charges"),
+        router: f(contract, "the warp route; it pulls the amount plus any fee it charges"),
         destinationDomain: f(uintN(32), "the destination's Hyperlane domain"),
         recipient: f(remoteRecipient, "receives on the destination"),
     }, { value: "the quoted gas payment, from the Pot" }),
     // -- wrapping -------------------------------------------------------------------------------
-    wrap("wrapETH", "Wraps native ETH into WETH.", "WETH.deposit", { weth: f(address, "the WETH contract") }, { output: "passThrough", value: "amount" }),
-    wrap("unwrapETH", "Unwraps WETH into native ETH.", "WETH.withdraw", { weth: f(address, "the WETH contract") }, { output: "passThrough" }),
+    wrap("wrapETH", "Wraps native ETH into WETH.", "WETH.deposit", { weth: f(tokenContract, 'the WETH contract ("WETH")') }, { output: "passThrough", value: "amount" }),
+    wrap("unwrapETH", "Unwraps WETH into native ETH.", "WETH.withdraw", { weth: f(tokenContract, 'the WETH contract ("WETH")') }, { output: "passThrough" }),
     wrap("wrapStETH", "Wraps stETH into wstETH; the output is the wstETH minted.", "wstETH.wrap", {
-        wstETH: f(address, "the wstETH contract; it pulls the stETH, so approve it first"),
+        wstETH: f(tokenContract, "the wstETH contract; it pulls the stETH, so approve it first"),
     }),
     wrap("unwrapStETH", "Unwraps wstETH; the output is the stETH returned.", "wstETH.unwrap", {
-        wstETH: f(address, "the wstETH contract"),
+        wstETH: f(tokenContract, "the wstETH contract"),
     }),
     // -- staking --------------------------------------------------------------------------------
     stake("lidoStake", "Stakes native ETH with Lido; the output is the stETH received.", "stETH.submit", {
-        stETH: f(address, "the stETH contract"),
+        stETH: f(tokenContract, "the stETH contract"),
         referral: opt(address, "Lido's referral; default the zero address"),
     }, { value: "amount" }),
     stake("lidoUnstake", "Requests a Lido withdrawal of stETH; the ETH is claimed later with the withdrawal NFT.", "WithdrawalQueueERC721.requestWithdrawals", {
-        withdrawalQueue: f(address, "Lido's withdrawal queue; it pulls the stETH, so approve it first"),
+        withdrawalQueue: f(contract, "Lido's withdrawal queue; it pulls the stETH, so approve it first"),
         owner: f(recipient, 'receives the withdrawal NFT; `"self"` is the Pot'),
     }, { output: "passThrough" }),
     stake("rocketPoolStake", "Stakes native ETH with Rocket Pool; the output is the rETH received.", "RocketDepositPool.deposit", {
-        depositPool: f(address, "the live RocketDepositPool, which upgrades move; read it from RocketStorage"),
-        rETH: f(address, "the rETH token, whose balance delta is the output"),
+        depositPool: f(contract, "the live RocketDepositPool, which upgrades move; read it from RocketStorage"),
+        rETH: f(tokenContract, "the rETH token, whose balance delta is the output"),
     }, { value: "amount" }),
     stake("rocketPoolUnstake", "Burns rETH; the output is the ETH received.", "rETH.burn", {
-        rETH: f(address, "the rETH token"),
+        rETH: f(tokenContract, "the rETH token"),
     }),
     stake("etherFiStake", "Stakes native ETH with ether.fi; the output is the eETH received.", "LiquidityPool.deposit", {
-        liquidityPool: f(address, "the ether.fi LiquidityPool"),
-        eETH: f(address, "the eETH token, whose balance delta is the output"),
+        liquidityPool: f(contract, "the ether.fi LiquidityPool"),
+        eETH: f(tokenContract, "the eETH token, whose balance delta is the output"),
     }, { value: "amount" }),
     // -- lending --------------------------------------------------------------------------------
     lending("aaveV3Supply", "Supplies a token to Aave V3.", "Pool.supply", {
-        pool: f(address, "the Aave V3 Pool; it pulls the token, so approve it first"),
-        token: f(address, "the asset supplied"),
+        pool: f(contract, "the Aave V3 Pool; it pulls the token, so approve it first"),
+        token: f(token, "the asset supplied"),
         onBehalfOf: f(recipient, 'credited with the position; `"self"` is the Pot'),
         referralCode: opt(uintN(16), "Aave's referral code; default 0"),
     }),
     lending("aaveV3Withdraw", "Withdraws a token from Aave V3; the output is the amount withdrawn.", "Pool.withdraw", {
-        pool: f(address, "the Aave V3 Pool"),
-        token: f(address, "the asset withdrawn"),
+        pool: f(contract, "the Aave V3 Pool"),
+        token: f(token, "the asset withdrawn"),
         recipient: f(recipient, 'receives the asset; `"self"` is the Pot'),
     }, { output: "realized" }),
     lending("aaveV3Borrow", "Borrows a token from Aave V3 at the variable rate, the only rate it offers.", "Pool.borrow", {
-        pool: f(address, "the Aave V3 Pool"),
-        token: f(address, "the asset borrowed"),
+        pool: f(contract, "the Aave V3 Pool"),
+        token: f(token, "the asset borrowed"),
         onBehalfOf: f(recipient, 'whose collateral backs the debt; `"self"` is the Pot'),
         referralCode: opt(uintN(16), "Aave's referral code; default 0"),
     }),
     lending("aaveV3Repay", "Repays an Aave V3 variable-rate debt.", "Pool.repay", {
-        pool: f(address, "the Aave V3 Pool; it pulls the token, so approve it first"),
-        token: f(address, "the asset repaid"),
+        pool: f(contract, "the Aave V3 Pool; it pulls the token, so approve it first"),
+        token: f(token, "the asset repaid"),
         onBehalfOf: f(recipient, 'whose debt is repaid; `"self"` is the Pot'),
     }),
     lending("compoundV3Supply", "Supplies a token to a Compound V3 (Comet) market.", "Comet.supply", {
-        comet: f(address, "the Comet market; it pulls the token, so approve it first"),
-        token: f(address, "the asset supplied"),
+        comet: f(contract, "the Comet market; it pulls the token, so approve it first"),
+        token: f(token, "the asset supplied"),
     }),
     lending("compoundV3Withdraw", "Withdraws a token from a Compound V3 (Comet) market.", "Comet.withdraw", {
-        comet: f(address, "the Comet market"),
-        token: f(address, "the asset withdrawn"),
+        comet: f(contract, "the Comet market"),
+        token: f(token, "the asset withdrawn"),
     }),
     // -- tokens ---------------------------------------------------------------------------------
-    token("transfer", "Transfers an ERC-20 token.", "ERC-20 transfer, checked like SafeERC20", {
-        token: f(address, "the token"),
+    tokens("transfer", "Transfers an ERC-20 token.", "ERC-20 transfer, checked like SafeERC20", {
+        token: f(token, "the token"),
         recipient: f(recipient, 'the receiver; `"self"` is the Pot'),
     }),
-    token("approve", "Approves an ERC-20 spender, resetting a non-zero allowance first.", "ERC-20 approve, checked and reset like SafeERC20.forceApprove", { token: f(address, "the token"), spender: f(address, "the spender") }),
-    token("permit2Approve", "Grants a spender a Permit2 allowance; the token must also be approved to Permit2.", "Permit2.approve(address,address,uint160,uint48)", {
-        permit2: f(address, "Permit2 (0x000000000022D473030F116dDEE9F6B43aC78BA3)"),
-        token: f(address, "the token"),
-        spender: f(address, "the spender, such as Balancer V3's router"),
+    tokens("approve", "Approves an ERC-20 spender, resetting a non-zero allowance first.", "ERC-20 approve, checked and reset like SafeERC20.forceApprove", { token: f(token, "the token"), spender: f(contract, "the spender") }),
+    tokens("permit2Approve", "Grants a spender a Permit2 allowance; the token must also be approved to Permit2.", "Permit2.approve(address,address,uint160,uint48)", {
+        permit2: f(contract, 'Permit2 ("Permit2.Permit2")'),
+        token: f(token, "the token"),
+        spender: f(contract, "the spender, such as Balancer V3's router"),
         expiration: f(uintN(48), "Unix seconds after which the allowance lapses"),
     }),
     // -- sources --------------------------------------------------------------------------------
-    source("balanceOf", "Reads the Pot's balance of a token; the output is that balance.", "IERC20.balanceOf(pot)", { token: f(address, "the token") }, { spends: false }),
+    source("balanceOf", "Reads the Pot's balance of a token; the output is that balance.", "IERC20.balanceOf(pot)", { token: f(token, "the token") }, { spends: false }),
     source("nativeBalance", "Reads the Pot's native balance; the output is that balance.", "ctx.selfBalance()", {}, { spends: false }),
     source("argument", "Declares a runtime argument of the compiled program; the output is the value supplied.", "a `main` parameter", { name: f({ k: "identifier" }, "the argument's name; arguments are encoded in order") }, { spends: false }),
 ];

package/actions/dist/split-swap.d.ts

@@ -1,7 +1,7 @@
+import { type ChainRef } from "../../sdk/dist/chains/canonical.js";
 import { type CompiledProgram } from "./compose.js";
 import { type QuoteOptions } from "./to-quote.js";
-import type { ApproveAction, SwapAction } from "./types.js";
-type Address = `0x${string}`;
+import type { ApproveAction, Recipient, SwapAction, Token } from "./types.js";
 /** A swap of `amount` split greedily, `buckets` slices at a time, across `candidates`. */
 export interface SplitSwap {
     /**
@@ -23,13 +23,18 @@ export interface SplitSwap {
     readonly approvals?: readonly ApproveAction[];
     /** Sends the total output of `token` to `recipient` at the end; omit to keep it in the Pot. */
     readonly sweep?: {
-        readonly token: Address;
-        readonly recipient: Address;
+        readonly token: Token;
+        readonly recipient: Recipient;
     };
     /** The quoter contracts the candidates price through. */
     readonly quoters?: QuoteOptions;
+    /**
+     * The chain the split runs on, which its token symbols and namespace references resolve on —
+     * needed when any candidate, approval or the sweep names one. Each name becomes its address
+     * there, because the quotes are calldata built here.
+     */
+    readonly chain?: ChainRef;
 }
 /** Compiles a split swap into one program. It takes no runtime arguments. */
 export declare function compileSplitSwap(swap: SplitSwap): CompiledProgram;
-export {};
 //# sourceMappingURL=split-swap.d.ts.map

package/actions/dist/split-swap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"split-swap.d.ts","sourceRoot":"","sources":["../src/split-swap.ts"],"names":[],"mappings":"AAmCA,OAAO,EAAY,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AAG9D,OAAO,EAAa,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7D,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE5D,KAAK,OAAO,GAAG,KAAK,MAAM,EAAE,CAAC;AAE7B,0FAA0F;AAC1F,MAAM,WAAW,SAAS;IACxB;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,SAAS,UAAU,EAAE,CAAC;IAC3C,gEAAgE;IAChE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,yEAAyE;IACzE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,8DAA8D;IAC9D,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IAC9C,+FAA+F;IAC/F,QAAQ,CAAC,KAAK,CAAC,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;KAAE,CAAC;IAC1E,yDAAyD;IACzD,QAAQ,CAAC,OAAO,CAAC,EAAE,YAAY,CAAC;CACjC;AAID,6EAA6E;AAC7E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,GAAG,eAAe,CAoFjE"}
+{"version":3,"file":"split-swap.d.ts","sourceRoot":"","sources":["../src/split-swap.ts"],"names":[],"mappings":"AAkCA,OAAO,EAGL,KAAK,QAAQ,EACd,MAAM,oCAAoC,CAAC;AAE5C,OAAO,EAAY,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AAK9D,OAAO,EAAa,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7D,OAAO,KAAK,EAAU,aAAa,EAAE,SAAS,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEtF,0FAA0F;AAC1F,MAAM,WAAW,SAAS;IACxB;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,SAAS,UAAU,EAAE,CAAC;IAC3C,gEAAgE;IAChE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,yEAAyE;IACzE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,8DAA8D;IAC9D,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IAC9C,+FAA+F;IAC/F,QAAQ,CAAC,KAAK,CAAC,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;QAAC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAA;KAAE,CAAC;IAC1E,yDAAyD;IACzD,QAAQ,CAAC,OAAO,CAAC,EAAE,YAAY,CAAC;IAChC;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC;CAC3B;AAID,6EAA6E;AAC7E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,GAAG,eAAe,CAsHjE"}

package/actions/dist/split-swap.js

@@ -24,15 +24,18 @@
  * constants here, so the emitted main is O(N + n·N) instructions.
  */
 import { formatBigint, fn, indent, newEmitter, } from "./emit.js";
+import { resolveChain, } from "../../sdk/dist/chains/canonical.js";
 import { contractsFor } from "./abis.js";
 import { compiled } from "./compose.js";
+import { resolveNames, usesNames } from "./names.js";
 import { parseActions } from "./program.js";
-import { lowerAction } from "./to-sauce.js";
+import { ProgramError } from "./semantics.js";
+import { lowerAction, routerImport } from "./to-sauce.js";
 import { quoteCall } from "./to-quote.js";
 const UINT_RE = /^(0|[1-9][0-9]*)$/;
 /** Compiles a split swap into one program. It takes no runtime arguments. */
 export function compileSplitSwap(swap) {
-    const candidates = parseActions(swap.candidates, "candidates");
+    let candidates = parseActions(swap.candidates, "candidates");
     candidates.forEach((candidate, i) => {
         for (const key of ["amount", "amountRef", "saveOutputAs"]) {
             if (candidate[key] !== undefined) {
@@ -40,7 +43,7 @@ export function compileSplitSwap(swap) {
             }
         }
     });
-    const approvals = parseActions(swap.approvals ?? [], "approvals");
+    let approvals = parseActions(swap.approvals ?? [], "approvals");
     approvals.forEach((approval, i) => {
         if (approval.type !== "approve" || approval.amount === undefined) {
             throw new Error(`approvals[${i}]: expected an \`approve\` action with an explicit \`amount\``);
@@ -48,6 +51,33 @@ export function compileSplitSwap(swap) {
     });
     if (candidates.length === 0)
         throw new Error("a split swap needs at least one candidate");
+    candidates.forEach((candidate, i) => {
+        if (candidate.factory !== undefined) {
+            throw new Error(`candidates[${i}].factory: a split quotes each candidate at its pool's address, and a pool ` +
+                "named by its key is found only while the program runs — give `pool`");
+        }
+    });
+    let sweep = swap.sweep;
+    const chain = swap.chain === undefined ? undefined : splitChain(swap.chain);
+    const sweepAction = sweep === undefined ? [] : [{ type: "transfer", amount: "0", ...sweep }];
+    if (usesNames([...candidates, ...approvals, ...sweepAction])) {
+        if (chain === undefined) {
+            throw new Error("a split swap that names a token or a contract needs `chain`, the chain to resolve it on");
+        }
+        const issues = [];
+        const named = (actions, path) => {
+            const result = resolveNames(actions, chain, path);
+            issues.push(...result.issues);
+            return result.resolved;
+        };
+        candidates = named(candidates, "candidates");
+        approvals = named(approvals, "approvals");
+        const [resolvedSweep] = named(sweepAction, "sweep");
+        if (sweep !== undefined)
+            sweep = { ...sweep, token: resolvedSweep.token };
+        if (issues.length > 0)
+            throw new ProgramError(issues, chain);
+    }
     const n = swap.buckets;
     if (!Number.isSafeInteger(n) || n < 1) {
         throw new Error(`buckets must be a positive integer, got ${n}`);
@@ -68,9 +98,12 @@ export function compileSplitSwap(swap) {
     const N = candidates.length;
     const emit = newEmitter();
     const bindings = new Set();
+    const router = new Set();
     const use = (result) => {
         for (const b of result.bindings)
             bindings.add(b);
+        for (const f of result.router)
+            router.add(f);
         return result;
     };
     const quoteFns = candidates.map((candidate, i) => {
@@ -93,13 +126,21 @@ export function compileSplitSwap(swap) {
     const swapAny = fn("swap_any", ["idx: Uint256", "amount: Uint256"], "Uint256", [
         ...outOfRangeGuard(N),
         ...blockDispatch(N, (i) => {
-            const built = use(lowerAction(emit, candidates[i], "amount", true));
+            const built = use(lowerAction(emit, candidates[i], "amount", true, `candidates[${i}]`));
             return [...built.stmts, `return ${built.output};`];
         }),
     ]);
-    const main = mainFn(emit, N, n, bucket, swap, approvals, use);
-    const source = [...quoteFns, quoteAny, swapAny, main].join("\n\n") + "\n";
-    return compiled(source, contractsFor(bindings), []);
+    const main = mainFn(emit, N, n, bucket, { ...swap, sweep }, approvals, use);
+    const source = routerImport([...router].sort()) + [...quoteFns, quoteAny, swapAny, main].join("\n\n") + "\n";
+    return compiled(source, contractsFor(bindings), [], {}, chain);
+}
+/** The split's chain, an EVM one the SDK knows. */
+function splitChain(ref) {
+    const chain = resolveChain(ref);
+    if (chain === undefined || chain.kind !== "evm") {
+        throw new Error(`a split swap runs on an EVM chain the SDK knows; got ${String(ref)}`);
+    }
+    return chain;
 }
 // ─────────────────────────────────────────────────────────────────────────────
 // Dispatchers

package/actions/dist/to-quote.d.ts

@@ -1,4 +1,5 @@
 import { type Emitter, type Expr, type Fragment } from "./emit.js";
+import { type ChainRef } from "../../sdk/dist/chains/canonical.js";
 import type { SwapAction } from "./types.js";
 type Address = `0x${string}`;
 type Hex = `0x${string}`;
@@ -23,11 +24,19 @@ export interface QuoteCall extends Quote {
  * the action names.
  */
 export interface QuoteOptions {
-    /** Uniswap's QuoterV2, for `uniswapV3ExactInput` and `uniswapV3ExactInputMultiHop`. */
-    readonly uniswapV3Quoter?: Address;
-    /** Uniswap's V4Quoter, for `uniswapV4ExactInput` and `uniswapV4ExactInputMultiHop`. */
-    readonly uniswapV4Quoter?: Address;
-    /** The MaverickV2Quoter, for `maverickSwap` and `maverickMultiHopSwap`. */
+    /**
+     * The chain the swap is on: needed when the action names a token or a contract, which resolve
+     * there to the addresses the quote calls.
+     */
+    readonly chain?: ChainRef;
+    /**
+     * The Sauce Router, for `uniswapV3Swap` and `uniswapV4Swap`: the contract that swaps them prices
+     * them, with its own `quote`, which needs no tokens. A Pot's Router is the Kitchen's Router until
+     * the Pot's owner moves it; `v12RouterAddress()` from `@eco-incorp/sauce/deployments` is the
+     * release's.
+     */
+    readonly router?: Address;
+    /** The MaverickV2Quoter, for `maverickV2Swap`. */
     readonly maverickQuoter?: Address;
     /** Ambient's CrocImpact, for `ambientSwap`. */
     readonly ambientImpact?: Address;