Cross-chain permits

Cross-chain permits define the cross-chain bridging scope available to a session. Set them at the session level via crossChainPermits, not per function. A session holding a permit is scoped: the session key can run only the calls its settlement routes need, funded only from the permit’s from tokens. It has no wildcard fallback unless you opt in with fallback.

A permit restricts bridging authority; it does not enable the session on another chain. For a transaction that uses the account on several chains, also configure Multi-chain sessions.

Basic usage

Restrict a session to bridging at most 100 USDC from Base to Arbitrum: Examples on this page use @rhinestone/sdk, where rhinestone is the RhinestoneSDK instance from Create a session with a custom setup.

import { parseUnits } from "viem";
import { arbitrum, base } from "viem/chains";

const usdcOnBase = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
const usdcOnArbitrum = "0xaf88d065e77c8cC2239327C5EDb3A432268e5831";

const session = await rhinestone.createSession({
  chain: base,
  owners: {
    type: "ecdsa",
    accounts: [sessionOwnerAccount],
  },
  account: rhinestoneAccount.getAddress("evm"),
  crossChainPermits: [
    {
      from: { chain: base, token: usdcOnBase, maxAmount: parseUnits("100", 6) },
      to: { chain: arbitrum, token: usdcOnArbitrum },
    },
  ],
});

console.log(session.access?.kind); // "scoped"
console.log(session.settlementLayers); // e.g. ["ACROSS", "CCTP"]
console.log(session.settlementCoverage?.dropped); // layers left out, with reasons

Field	Description
`from`	Source chain and token, with an optional `maxAmount`. Pass one leg or an array.
`to`	Destination chain and token, with an optional `recipient` pin and `minAmount`.
`account`	Set on the session definition. Layers that pin the recipient in their calldata, such as `CCTP`, need the address.

Pass each token’s address on its own chain. Without fallback, a Permit2-layer permit needs a from token on the session’s chain. Without account, a permit that delivers to the account and can settle through CCTP is refused with RECIPIENT_NEEDS_ACCOUNT. Create permit sessions with rhinestone.createSession. It reads the settlement addresses the Orchestrator serves, which the IntentExecutor layers pin. Run rhinestone.validateSession first to list every refusal and warning.

Settlement layers

A permit settles through one or more settlement layers:

Layer	Kind	Moves	Notes
`ACROSS`	Permit2	Tokens Across serves	No per-call amount cap or output floor. Bounded by `maxAmount` and the claim’s token, chain and recipient.
`CCTP`	IntentExecutor	USDC	Needs `account` when delivering to the account. Cannot enforce `to.minAmount`.
`OFT`	IntentExecutor	USDT0	Requires `oneTimeUse`.
`LZ`	IntentExecutor	USDC through Stargate or CCTP	Requires `oneTimeUse`. Cannot be combined with `OFT`.
`ECO_IE`	IntentExecutor	USD stablecoins the Orchestrator serves	Needs `maxAmount` and a floor (`maxFeeBps` or `to.minAmount`).
`SAME_CHAIN_IE`	IntentExecutor	A transfer or one swap on the session’s chain	Must be the only layer. Never selected by default.
`SAME_CHAIN`	Permit2	Same-chain settlement	Only with `fallback`.

IntentExecutor layers pin their calls, including the recipient, in calldata. A session can hold one IntentExecutor-layer permit.

ECO, the retired Permit2 Eco arbiter, is refused with RETIRED_PERMIT2_LAYER. Use ECO_IE instead.

Default coverage

Omit settlementLayers, or pass [] or "all", to select ACROSS plus every IntentExecutor layer among CCTP, OFT, ECO_IE and LZ that can settle the permit on the session’s chain. The SDK leaves out the rest and records them in session.settlementCoverage.dropped with the reason. session.settlementLayers lists the layers it kept. For the basic example above, OFT and LZ are dropped because they require oneTimeUse, and ECO_IE because the permit sets no floor. Treat this as example output: coverage resolves against the served catalog and the clock when you create the session, so inspect settlementCoverage rather than assuming a route is available, and store the created session instead of rebuilding it from the definition. SAME_CHAIN_IE is never selected by default. If no layer qualifies, the session is refused with NO_LAYER_CAN_SETTLE.

Explicit layers

Name layers to make the list strict. Every named layer must be able to settle the permit, or the session is refused with that layer’s reason. The order does not matter:

const session = await rhinestone.createSession({
  chain: base,
  owners: {
    type: "ecdsa",
    accounts: [sessionOwnerAccount],
  },
  account: rhinestoneAccount.getAddress("evm"),
  crossChainPermits: [
    {
      from: { chain: base, token: usdcOnBase, maxAmount: parseUnits("100", 6) },
      to: { chain: arbitrum, token: usdcOnArbitrum },
      settlementLayers: ["ACROSS", "CCTP"],
    },
  ],
});

Combination rules:

SAME_CHAIN_IE must be the only layer.
OFT and LZ cannot be combined, and each requires oneTimeUse (LAYER_REQUIRES_ONE_TIME_USE).
IntentExecutor layers need named to chains.
ACROSS is the only Permit2 layer you can name without fallback.

An intent’s own settlementLayers filter can only narrow the session’s layers.

Spending budgets

maxAmount on a from leg caps what the session can move from that token on its chain, across every route the permit settles through:

With oneTimeUse, it caps one settlement.
Without it, it is a lifetime total shared by every intent the session signs, not a per-intent cap.

maxAmount caps the approvals the session makes. It does not count allowances the account already holds, such as one the owner gave Permit2 or a bridge, or one another session left. Those remain spendable by the session’s routes, so revoke them first if maxAmount must be the most the session can move. allowFees calls have separate caps. Set maxAmount on each from leg on the session’s chain. When ACROSS sits beside IntentExecutor layers and a leg has no maxAmount, nothing caps what the ACROSS route moves for it, and validateSession warns with UNCAPPED_ACROSS_ROUTE. Re-enabling a session that is already enabled resets its lifetime budget, so getSessionDetails refuses it by default. See Re-enable a session with a lifetime budget. A reusable (no oneTimeUse) scoped ACROSS session needs the Permit2SenderPolicy on the session’s chain. On chains without it, such as Avalanche, the session is refused with PERMIT2_ROUTE_NEEDS_BOUND. Use oneTimeUse there.

Time windows

Bound the permit with validAfter and validUntil, and bound the fill per destination chain with fillDeadline:

const session = await rhinestone.createSession({
  chain: base,
  owners: {
    type: "ecdsa",
    accounts: [sessionOwnerAccount],
  },
  crossChainPermits: [
    {
      from: { chain: base, token: usdcOnBase, maxAmount: parseUnits("100", 6) },
      to: { chain: arbitrum, token: usdcOnArbitrum },
      settlementLayers: ["ACROSS"],
      validAfter: new Date(),
      validUntil: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000),
      fillDeadline: [
        { chain: arbitrum, max: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000) },
      ],
    },
  ],
});

validAfter / validUntil apply to every action the permit adds. On ACROSS they also bound the Permit2 deadline. validUntil must be a future Date.
fillDeadline applies to ACROSS only.
ECO_IE needs any validUntil at least 7 days ahead, and is usable only until 7 days before it.

See Timeframe for the window semantics shared by every session window.

Recipient safety

By default a cross-chain permit enforces bridge-to-self on-chain: the destination recipient must be the smart account itself. This stops a leaked session key from routing funds to an attacker-controlled address. Opt out explicitly only when you need to bridge to a different recipient:

const session = await rhinestone.createSession({
  chain: base,
  owners: {
    type: "ecdsa",
    accounts: [sessionOwnerAccount],
  },
  crossChainPermits: [
    {
      from: { chain: base, token: usdcOnBase, maxAmount: parseUnits("100", 6) },
      to: [
        { chain: arbitrum, token: usdcOnArbitrum, recipient: payoutAddress },
      ],
      allowRecipientNotAccount: true,
    },
  ],
});

ACROSS enforces the recipient in its claim policy; IntentExecutor layers pin it in calldata.

Fees and delivery floors

By default a scoped permit session settles only sponsored intents without an app fee or a user-paid protocol fee taken from the from token. On IntentExecutor layers it also refuses unsponsored gas. These opt-ins widen or tighten that:

Option	Effect
`allowFees: true`	Lets the session pay the app fee, a user-paid protocol fee, and unsponsored gas. Each fee call has its own cumulative cap of 5 USD (30 USD on Ethereum mainnet). `from` tokens must be served USD stablecoins with the same decimals.
`maxFeeBps`	`ECO_IE` only, and refused beside `ACROSS`. The route must deliver at least `maxAmount × (1 − maxFeeBps / 10000)`. This floors the cap, not the amount an intent actually sends.
`to.minAmount`	Minimum delivery for `ECO_IE`, `OFT`, `LZ` (Stargate legs), and required for `SAME_CHAIN_IE` swaps. Values outside half of to all of `maxAmount` are refused as a units mistake.

An intent whose fee or gas ceiling exceeds the remaining allowFees cap fails closed. OFT and LZ quote with about 1% slippage, so set to.minAmount to at most about 99% of the expected send. Every layer in the permit must enforce to.minAmount. CCTP cannot, so it is refused when named and dropped by default coverage. ACROSS has no output floor. Fee and floor coverage applies only to the paths each policy enforces; it is not a universal spending bound.

Open fallback

Set fallback to give a permit session a wildcard action beside its scoped calls:

const session = await rhinestone.createSession({
  chain: base,
  owners: {
    type: "ecdsa",
    accounts: [sessionOwnerAccount],
  },
  fallback: "intentExecution",
  crossChainPermits: [
    {
      from: { chain: base, token: usdcOnBase },
      to: { chain: arbitrum, token: usdcOnArbitrum },
    },
  ],
});

"intentExecution" also allows the calls Rhinestone’s intent-execution policy admits. Rhinestone sets that policy, and it may admit more over time.
"sudo" allows any call, with any arguments and native value.

Either value makes session.access.kind "open", and lets intents take routes other than ACROSS and fund them from any asset. With fallback:

Omitted layers mean ACROSS, and "all" is refused.
Only Permit2-layer permits (ACROSS, SAME_CHAIN) qualify. IntentExecutor layers, restrictToActions, and swap are refused with FALLBACK_NOT_APPLICABLE.
The recipient pin holds only for intents settled through ACROSS (warning FALLBACK_RECIPIENT_PIN_ACROSS_ONLY).
maxAmount requires oneTimeUse.

Do not add fallback just to make an incompatible scope compile. Fix the scope instead, or declare the extra actions you need.

Scoped session behavior

A scoped permit session settles cross-chain intents only, or with a swap scope, same-chain intents funded from its sell tokens. A destination call or leftover sweep on the destination chain needs the destination chain’s session to declare those actions, or to set fallback. You can combine a permit with restrictToActions, permissions, and actions to let the same key run other explicit calls.

Embedded wallet

Custom setup

Basic usage

Settlement layers

Default coverage

Explicit layers

Spending budgets

Time windows

Recipient safety

Fees and delivery floors

Open fallback

Scoped session behavior

​Basic usage

​Settlement layers

​Default coverage

​Explicit layers

​Spending budgets

​Time windows

​Recipient safety

​Fees and delivery floors

​Open fallback

​Scoped session behavior

Basic usage

Settlement layers

Default coverage

Explicit layers

Spending budgets

Time windows

Recipient safety

Fees and delivery floors

Open fallback

Scoped session behavior