Names

​

How a name resolves

// Pays `amount` of the chain's USDC from the Pot to `to`.
function main(to: Address, amount: Uint256) {
  require(pot.USDC >= amount, "not enough USDC");
  USDC.transfer(to, amount);
}

• Resolution is per chain and happens at compile time. Nothing of the name is left in the bytecode; the engine on chain only reads addresses.
• sauce compile --json lists what was applied. defines holds each token and chainId with its value, and contracts holds each namespace contract with its address (addresses abbreviated here):
  {
    "defines": [
      { "name": "USDC", "value": "0x8335…2913", "source": "chain", "kind": "token", "chain": "base" }
    ]
  }
  
• A use of a name the chain lacks is a compile error at the use, naming the chain. The error gives the file, line and column. Nothing is compiled, so nothing can be sent. This program compiles for Ethereum, which registers USDT:
  missing-token.sauce.ts

  // Pays `amount` of the chain's USDT from the Pot to `to`.
  function main(to: Address, amount: Uint256) {
    USDT.transfer(to, amount);
  }
  
  Base does not register USDT, so --chain base fails like this at USDT.transfer:
  `USDT` is not a token on base. Did you mean `USDC`? A token the chain lacks is zero there, and only a test of it may use it: `if (USDT) { … }` compiles the branch only where the chain has it. It is a token on ethereum, optimism, solana. …
  hint: USDT is not a registered token on base (it has USDC, WETH, 67 stock tokens): take its address as a parameter of main …
  
• A protocol contract the chain lacks is refused the same way, with the chains that have it. This program compiles for Base:
  missing-contract.sauce.ts

  // Returns the 0.05% Uniswap V3 pool of `tokenA` and `tokenB`, or 0 when there is none.
  function main(tokenA: Address, tokenB: Address): Uint256 {
    return UniswapV3.Factory.getPool(tokenA, tokenB, 500);
  }
  
  Compiled with --chain unichain, it fails:
  `UniswapV3.Factory` is not deployed on unichain. A contract the chain lacks is zero there, and only a test of it may use it: `if (UniswapV3.Factory) { … }` compiles the branch only where the chain has it. It is deployed on ethereum, optimism, bsc, polygon, monad, arc, base, arbitrum and 2 more.
  
  To use a name only on the chains that have it, test it: Using a name only where the chain has it.

​

Token symbols

• Symbols are case-sensitive. SPCXC is not SPCXc.
• Not every chain registers symbols. Only 19 of the 46 registry chains register any: Ethereum, Optimism, Unichain, Polygon, Monad, Sei, Mantle, Arc, Base, Plasma, Arbitrum, Ink, Berachain and Solana, and the testnets Arc Testnet, Base Sepolia, Ethereum Sepolia, Solana Devnet and Solana Testnet. Among those, the symbols differ: Base has USDC and WETH, Ethereum adds USDT, Unichain has only USDT0. On a chain that does not register a symbol, take the address as a main parameter and use Token(address).
• Tokenized stocks are tokens. Each issuer’s own ticker is the symbol, with . written as _ (BRK.Bx is BRK_Bx). They take the same methods, balances and swaps as any token:
  stock.sauce.ts

  // Pays `amount` of Coinbase's tokenized SpaceX from the Pot to `to`.
  function main(to: Address, amount: Uint256) {
    require(pot.SPCXc >= amount, "not enough SPCXc");
    SPCXc.transfer(to, amount);
  }
  
  The chain’s stocks are not in its sauce globals token list, which counts them. sauce globals --chain base --stocks lists them and --search spacex finds one by symbol, company or ticker. One company has one token per issuer, so the symbol depends on the chain and the issuer.
• A wrong case is refused, with the right one suggested. On Base, SPCXC.transfer(to, amount) fails with this hint; write SPCXc, as stock.sauce.ts does:
  hint: SPCXC is SPCXc on base: a token's symbol is case-sensitive
  

​

Balances

// Adds the USDC the Pot holds, the USDC `account` holds, the WETH held by the
// Uniswap V4 PoolManager, the ETH locked in the WETH contract and the Pot's ETH.
function main(account: Address): Uint256 {
  return pot.USDC + account.USDC + UniswapV4.PoolManager.WETH + WETH.balance + pot.balance;
}

• pot is the Pot, and pot.USDC is the Pot’s USDC.
• The native coin is .balance. pot.balance is ctx.selfBalance(), and account.balance is ctx.balance(account). On Solana pot.balance is the Pot’s lamports. .<SYMBOL> reads only a token the chain registers.
• A holder on an EVM chain is any address: pot or ctx.self(), a variable or parameter, a protocol contract (UniswapV4.PoolManager), a contract at an address (UniswapV3.Pool(pool)), a call that returns an address, or a token contract (WETH.balance is the ETH locked in WETH).
• A holder on Solana must be known when the transaction is built, because its account is added to main: pot, pot.owner, an Address parameter of main, a token’s mint, or a 32-byte key written out.
• .balance on a value that is not an address reads a field: a record, a list, a value abi.decode returns, or a struct a contract call returns. For the native coin of an address such a value holds, write ctx.balance(x).

​

The Pot’s owner and account names

​

Arc: one balance, two scales

// Reverts unless the Pot holds at least `minWei` of the native coin (18 decimals)
// and at least `minUnits` of the ERC-20 USDC (6 decimals). Both read the same balance.
function main(minWei: Uint256, minUnits: Uint256) {
  require(pot.balance >= minWei, "native balance too low");
  require(pot.USDC >= minUnits, "token balance too low");
}

​

Token(address) and bound tokens

// Pays `amount` of `token` from the Pot to `to`.
function main(token: Address, to: Address, amount: Uint256) {
  const t = Token(token);
  require(t.balanceOf(pot) >= amount, "not enough tokens");
  t.transfer(to, amount);
}

• the binding is declared once with const, in the whole program;
• it is never reassigned;
• it is used only as t.method(…).

`t = Token(...)`: `t` is used other than as `t.<method>(...)`. `Token(addr)` is supported as the receiver of a call (`Token(addr).transfer(to, amount)`) or bound once to a local that is only ever called (`const t = Token(addr); t.approve(spender, amount)`). …

​

Token methods

• A token that returns nothing, such as USDT, works when the address has code. A false return, a malformed return, or an address with no code reverts the program.
• A write returns nothing, so its result cannot be used. const ok = USDC.transfer(to, amount); fails with the message below; call the write as a statement, as token-functions.sauce.ts does:
  `USDC.transfer(...)` returns nothing, so its result cannot be used: a token write has SafeERC20 semantics and reverts the program unless the token accepted it. Call it as a statement.
  
• Approve the amount the next call spends and no more. An allowance that the program leaves standing outlives the program.

​

The same functions without a method

// Reverts unless `spender` has no USDC allowance left from the Pot after the transfer.
function main(spender: Address, to: Address, amount: Uint256) {
  transfer(USDC, to, amount);
  require(allowance(USDC, pot, spender) == 0, "no allowance left standing");
  require(decimals(USDC) == 6, "unexpected decimals");
}

​

Protocol namespaces

// Reads a pool the program is given, and the pool the factory finds for WETH/USDC.
function main(pool: Address): Uint256 {
  const provider = AaveV3.PoolAddressesProvider;
  require(provider != 0, "no provider");
  const found = UniswapV3.Factory.getPool(WETH, USDC, 500);
  return UniswapV3.Pool(pool).liquidity() + found.liquidity();
}

• An interface is called with an address in the same expression: UniswapV3.Pool(pool).slot0(). UniswapV3.Pool.at(pool) is the same. A deployed contract’s name is never called with an address; .at(address) reaches another deployment of its ABI.
• A contract a call returns is called directly where the registry records what the returned address is: found.liquidity() above, and Erc4626.Vault(vault).asset().decimals(). Contracts and ABIs covers calls.
• A namespace’s default contract is called by the namespace alone when the namespace has exactly one deployed contract with an ABI. AaveV3.supply(…) calls AaveV3.Pool.supply(…). A namespace with several contracts, such as UniswapV3, needs the contract’s name.
• A family alias groups a protocol’s versions. Uniswap covers UniswapV2, UniswapV3 and UniswapV4, and Aave covers AaveV2, AaveV3 and AaveV4. An alias names a contract only when exactly one member has it on the chain.
  alias.sauce.ts

  // The only Uniswap version with a UniversalRouter is V4.
  function main(): Uint256 {
    return Uniswap.UniversalRouter;
  }
  
  Uniswap.Factory exists in V2 and V3, so it is ambiguous. return Uniswap.Factory; fails with the message below; name the version, UniswapV3.Factory, as namespaces.sauce.ts does:
  `Uniswap.Factory` is ambiguous under Uniswap (uniswap-v2, uniswap-v3): write `UniswapV2.Factory` or `UniswapV3.Factory`
  
• A chain-qualified contract is another chain’s address and nothing more. A chain name qualifies the namespace:
  qualified.sauce.ts

  // Ethereum's UniversalRouter address, as a value, in a program compiled for Base.
  function main(): Address {
    return Ethereum.UniswapV4.UniversalRouter;
  }
  
  The program still runs on the chain it is compiled for. A call through the qualified name is a call to that address on this chain, where it is some other contract or none, and the compiler does not stop it. Pass a qualified name to something that acts on the other chain; never call it. A token is never qualified: the symbol is always the compiled-for chain’s.

​

Using a name only where the chain has it

// Finds a 0.05% pool where the chain has Uniswap V3, and pays in USDT where the chain has it, else in USDC.
function main(tokenA: Address, tokenB: Address, to: Address, amount: Uint256): Uint256 {
  let pool = 0;
  if (UniswapV3.Factory) {
    pool = UniswapV3.Factory.getPool(tokenA, tokenB, 500);
  }
  if (USDT) {
    USDT.transfer(to, amount);
  } else {
    USDC.transfer(to, amount);
  }
  return pool;
}

• A test is the name in a condition: if (X), !X, X != 0, X == 0, X ? a : b, X && … and X || …. X is a contract (UniswapV3.Factory, Uniswap.UniversalRouter, or one on a named chain, Arbitrum.UniswapV3.Factory) or a token symbol (USDT). A guard that returns, if (!USDT) return 0;, leaves out the rest of its block where USDT is absent.
• Any other use of a name the chain lacks is refused at the use, naming the chain: a call on it, passing it, returning it, or const a = X. A zero never reaches the chain as a contract address. require(X != 0) on a chain without X is refused too, since it fails whatever the program does.
• A decision is made only from registry names, true and false, !, &&, || and comparisons with 0. X > 0 is a use of X, not a test. A decision held in a variable is live code: with const has = USDT != 0; if (has) { USDT.transfer(to, amount); }, Base refuses the transfer. A helper function is checked as if it ran, so it tests the name itself.
• Outside a condition, X && Y and X || Y give true or false, and each side is a test: const both = USDT && UniswapV3.Factory; compiles on Base, where USDT is absent. On a contract they give a bool too: const factory = UniswapV3.Factory; return factory || 0; returns true, not the factory’s address.
• A name no chain has is an error on every chain, tested or not, so a typo cannot drop a branch. if (UniswapV9.Factory) { … } fails on Base with “UniswapV9 is not a token or protocol on base. Did you mean UniswapV2 or UniswapV3 or UniswapV4? …”, and the same holds for a contract or method the registry does not have.
• A program’s own declaration wins. A local, parameter or function named like a registry name is the program’s in the block it is declared in, from the declaration on. A type-only import (import type { USDT }) declares nothing.
• A program that declares its own function named available keeps it. A registry name is tested by the name itself, never by a call.

​

Chain names and chainId

• A chain name (Base, Ethereum, Arc, Solana) qualifies another chain’s contract address, as above. Chains lists each name.
• chainId is the id of the chain the program was compiled for. It is a constant folded into the bytecode.

// Reverts when these bytes run on a chain other than the one they were compiled for.
function main() {
  require(ctx.chainId() == chainId, "compiled for another chain");
}

​

Solana venue namespaces

// Swaps `amountIn` USDC for WSOL at the Orca whirlpool for the USDC/WSOL pair at tick spacing 4,
// and pays the WSOL to `to`.
function main(to: Address, amountIn: Uint256, priceLimit: Uint256, minOut: Uint256): Uint256 {
  const got = Orca.Whirlpool.swap(Orca.Whirlpool.pool(USDC, WSOL, 4), USDC, WSOL, amountIn, priceLimit, minOut);
  if (got > 0) {
    WSOL.transfer(to, got);
  }
  return got;
}

​

Next steps