From 510e6fffcb5f31dccb5dc9c828ba881955744bdf Mon Sep 17 00:00:00 2001 From: Arnau Bennassar Date: Wed, 14 Oct 2026 22:15:52 +0000 Subject: [PATCH 1/7] docs: add AGGLAYER provider, Bali chains and ETA behaviour (agglayer/issues#46) --- resources/supported-chains.mdx | 14 ++++++++++++++ sdk/quote-providers.mdx | 13 +++++++++++++ 2 files changed, 27 insertions(+) diff --git a/resources/supported-chains.mdx b/resources/supported-chains.mdx index e373a0c..2a14b70 100644 --- a/resources/supported-chains.mdx +++ b/resources/supported-chains.mdx @@ -44,6 +44,19 @@ Trails supports **edge chains** — non-EVM ecosystems reached through edge rail | Solana | SVM | 101 | SOL | ✅ Supported | | Tron | TVM | 728126428 | TRX | ✅ Supported | +## Testnet Chains + +Trails supports the following AggLayer Bali pilot testnet chains, which settle to the Sepolia testnet L1 (chain id `11155111`) and bridge via the [`AGGLAYER`](/sdk/quote-providers) provider: + +| Chain | Chain ID | Type | Native Token | Status | +|-------|----------|------|--------------|--------| +| Bali PP | 82 | AggLayer pessimistic proof | ETH | ✅ Pilot | +| Bali FEP | 85 | AggLayer front-end provers (FEP) | ETH | ✅ Pilot | + + +The Bali chains are AggLayer pilot networks registered in `agglayer/networks`. Bridge transfers on these chains wait for the quote's completion estimate (see [Route Providers](/sdk/quote-providers) for ETA and slow-route expectations). + + ## Stablecoin Details ### USDC Availability @@ -113,6 +126,7 @@ Trails routes transactions through the optimal liquidity source for each transfe | **LayerZero Transfer** | `LZ_TRANSFER` | Bridge | LayerZero Value Transfer API; explicit selection only | | **Open Intents Framework** | `OIF` | Bridge | Solver-filled cross-chain intents; explicit selection only | | **Gas.zip** | `GASZIP` | Bridge | Gas-optimized cross-chain routing | +| **AggLayer** | `AGGLAYER` | Bridge | AggLayer unified bridge; Bali pilot testnet chains 82/85 | | **LI.FI** | `LIFI` | Bridge / DEX aggregator | Aggregated cross-chain and same-chain routing | | **0x Protocol** | `ZEROX` | DEX aggregator | Best execution routing across multiple DEXs | | **SushiSwap** | `SUSHI` | DEX | On-chain swap routing with V3 concentrated liquidity | diff --git a/sdk/quote-providers.mdx b/sdk/quote-providers.mdx index fddc205..a48651a 100644 --- a/sdk/quote-providers.mdx +++ b/sdk/quote-providers.mdx @@ -20,6 +20,7 @@ Trails integrates with multiple liquidity sources and bridge providers to find t - **`HYPERLANE`**: Uses Hyperlane warp routes for cross-chain messaging - **`OIF`**: Uses the Open Intents Framework for solver-filled cross-chain intents - **`GASZIP`**: Uses Gas.zip for gas-optimized routing +- **`AGGLAYER`**: Uses the AggLayer unified bridge (Polygon AggLayer) - **`WETH`**: Wrap/unwrap ETH ↔ WETH on the same chain - **`SOMNIA_EXCHANGE`**: Uses Somnia Exchange for swaps on Somnia - **`SOMNIA_SWAP`**: Uses Somnia Swap for swaps on Somnia @@ -176,6 +177,18 @@ Gas.zip is a gas-optimized routing provider that reduces the total gas cost of c ``` +### AggLayer + +AggLayer routes transfers over the AggLayer unified bridge (Polygon AggLayer). It currently serves the Bali pilot testnet chains — chain `82` (PP) and chain `85` (FEP), which settle to the Sepolia testnet L1 (chain id `11155111`). AggLayer routes require an explicit `bridgeProvider="AGGLAYER"` selection. + +```tsx + +``` + +- **ETA-driven waits**: the quote's completion estimate drives the SDK's receipt-polling window and the widget's slow-route warnings. AggLayer waits are raised to a per-direction corridor floor — 20 minutes for transfers entering from the L1, 3 hours for exits — and to 1.5× the quote's estimate when that is longer. A pre-commit banner appears when the estimate is 10 minutes or more. +- **Slow routes**: hops originating on the FEP chain (`85`) wait for an L1 global exit root change before they can be claimed, and can take 90 minutes or more. Typical completions are shorter — roughly 10–15 minutes for `82` → `85` and about 20 minutes for `85` → `82` — but budget for the slow path. +- **L1 data fee**: receipts on both corridors include an L1 data fee. The first claim of a token costs about 1.02M gas, a repeat ERC-20 claim about 228k, and an ETH claim about 150k. + ### Somnia (SOMNIA_EXCHANGE / SOMNIA_SWAP) Native swap providers on Somnia (chain id `5031`). Used for on-chain swaps within Somnia. From 01575706cf2d744b26ff19d5d07d509c1b18bb57 Mon Sep 17 00:00:00 2001 From: Arnau Bennassar Date: Thu, 15 Oct 2026 17:56:35 +0000 Subject: [PATCH 2/7] fix: use real Bali EVM chain IDs (828282/858585); rollup IDs are 82/85 Verified on-chain via eth_chainId (agglayer/issues#39, gke configs, live RPC). Also drop the agglayer/networks registry reference (superseded by the SDK chain registry). Refs agglayer/issues#46. --- resources/supported-chains.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/resources/supported-chains.mdx b/resources/supported-chains.mdx index 2a14b70..9ba3224 100644 --- a/resources/supported-chains.mdx +++ b/resources/supported-chains.mdx @@ -50,11 +50,11 @@ Trails supports the following AggLayer Bali pilot testnet chains, which settle t | Chain | Chain ID | Type | Native Token | Status | |-------|----------|------|--------------|--------| -| Bali PP | 82 | AggLayer pessimistic proof | ETH | ✅ Pilot | -| Bali FEP | 85 | AggLayer front-end provers (FEP) | ETH | ✅ Pilot | +| Bali PP | 828282 | AggLayer pessimistic proof | ETH | ✅ Pilot | +| Bali FEP | 858585 | AggLayer front-end provers (FEP) | ETH | ✅ Pilot | -The Bali chains are AggLayer pilot networks registered in `agglayer/networks`. Bridge transfers on these chains wait for the quote's completion estimate (see [Route Providers](/sdk/quote-providers) for ETA and slow-route expectations). +The Bali chains are AggLayer pilot networks (rollup IDs 82 and 85 — the table lists their EVM chain IDs). Bridge transfers on these chains wait for the quote's completion estimate (see [Route Providers](/sdk/quote-providers) for ETA and slow-route expectations). ## Stablecoin Details From 1f5da4bdb78e1cc6e5a3f97d6ecdcde37d80d894 Mon Sep 17 00:00:00 2001 From: Arnau Bennassar Date: Thu, 15 Oct 2026 18:27:58 +0000 Subject: [PATCH 3/7] =?UTF-8?q?docs:=20address=20review=20=E2=80=94=20chai?= =?UTF-8?q?n=20IDs=20vs=20rollup=20IDs,=20ETA=20floor=20model,=20AggLayer?= =?UTF-8?q?=20example=20(agglayer/issues#46)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Use EVM chain IDs 828282/858585 in the provider table, AggLayer intro and slow-routes text; label 82/85 as AggLayer rollup IDs everywhere - Rewrite the ETA section per the SDK implementation: direction is set by the quote's origin chain (L1 origin = entry, any L2 origin = exit, including Bali-to-Bali hops), entries floor at 20 minutes and exits at 3 hours, the displayed estimate is the estimate raised to the floor, and the receipt-polling window is max(estimate x 1.5, floor) - Recast the 'L1 data fee' bullet as user-paid claim gas - Extend the AggLayer config example with from/to on the Bali chain IDs - Add Sepolia (11155111) to the testnet table — verified supported in the SDK chain registry (supportedSequenceTestnetChains/ALL_CHAINS) - Note there is no public block explorer for the Bali chains yet, that AGGLAYER ships with the upcoming SDK release, tighten the Note, link the ETA anchor, and standardize on 'AggLayer' --- resources/supported-chains.mdx | 7 ++++--- sdk/quote-providers.mdx | 23 +++++++++++++++++------ 2 files changed, 21 insertions(+), 9 deletions(-) diff --git a/resources/supported-chains.mdx b/resources/supported-chains.mdx index 9ba3224..2ffc7b4 100644 --- a/resources/supported-chains.mdx +++ b/resources/supported-chains.mdx @@ -46,15 +46,16 @@ Trails supports **edge chains** — non-EVM ecosystems reached through edge rail ## Testnet Chains -Trails supports the following AggLayer Bali pilot testnet chains, which settle to the Sepolia testnet L1 (chain id `11155111`) and bridge via the [`AGGLAYER`](/sdk/quote-providers) provider: +Trails supports the following testnet chains. The Bali pilot networks settle to the Sepolia testnet L1 (chain ID `11155111`) and bridge via the [`AGGLAYER`](/sdk/quote-providers#agglayer) provider: | Chain | Chain ID | Type | Native Token | Status | |-------|----------|------|--------------|--------| +| Sepolia | 11155111 | Ethereum testnet L1 | ETH | ✅ Supported | | Bali PP | 828282 | AggLayer pessimistic proof | ETH | ✅ Pilot | | Bali FEP | 858585 | AggLayer front-end provers (FEP) | ETH | ✅ Pilot | -The Bali chains are AggLayer pilot networks (rollup IDs 82 and 85 — the table lists their EVM chain IDs). Bridge transfers on these chains wait for the quote's completion estimate (see [Route Providers](/sdk/quote-providers) for ETA and slow-route expectations). +The Bali chains are AggLayer pilot networks — rollup IDs 82 and 85; the table lists their EVM chain IDs. No public block explorer exists for either chain yet. AggLayer transfers display and poll the quote's completion estimate raised to a direction floor (20 minutes from an L1 origin, 3 hours from an L2 origin) with 1.5× headroom — see [AggLayer](/sdk/quote-providers#agglayer). ## Stablecoin Details @@ -126,7 +127,7 @@ Trails routes transactions through the optimal liquidity source for each transfe | **LayerZero Transfer** | `LZ_TRANSFER` | Bridge | LayerZero Value Transfer API; explicit selection only | | **Open Intents Framework** | `OIF` | Bridge | Solver-filled cross-chain intents; explicit selection only | | **Gas.zip** | `GASZIP` | Bridge | Gas-optimized cross-chain routing | -| **AggLayer** | `AGGLAYER` | Bridge | AggLayer unified bridge; Bali pilot testnet chains 82/85 | +| **AggLayer** | `AGGLAYER` | Bridge | AggLayer unified bridge; Bali pilot testnet chains (828282, 858585) | | **LI.FI** | `LIFI` | Bridge / DEX aggregator | Aggregated cross-chain and same-chain routing | | **0x Protocol** | `ZEROX` | DEX aggregator | Best execution routing across multiple DEXs | | **SushiSwap** | `SUSHI` | DEX | On-chain swap routing with V3 concentrated liquidity | diff --git a/sdk/quote-providers.mdx b/sdk/quote-providers.mdx index a48651a..078ecb4 100644 --- a/sdk/quote-providers.mdx +++ b/sdk/quote-providers.mdx @@ -20,7 +20,7 @@ Trails integrates with multiple liquidity sources and bridge providers to find t - **`HYPERLANE`**: Uses Hyperlane warp routes for cross-chain messaging - **`OIF`**: Uses the Open Intents Framework for solver-filled cross-chain intents - **`GASZIP`**: Uses Gas.zip for gas-optimized routing -- **`AGGLAYER`**: Uses the AggLayer unified bridge (Polygon AggLayer) +- **`AGGLAYER`**: Uses the AggLayer unified bridge - **`WETH`**: Wrap/unwrap ETH ↔ WETH on the same chain - **`SOMNIA_EXCHANGE`**: Uses Somnia Exchange for swaps on Somnia - **`SOMNIA_SWAP`**: Uses Somnia Swap for swaps on Somnia @@ -179,15 +179,26 @@ Gas.zip is a gas-optimized routing provider that reduces the total gas cost of c ### AggLayer -AggLayer routes transfers over the AggLayer unified bridge (Polygon AggLayer). It currently serves the Bali pilot testnet chains — chain `82` (PP) and chain `85` (FEP), which settle to the Sepolia testnet L1 (chain id `11155111`). AggLayer routes require an explicit `bridgeProvider="AGGLAYER"` selection. +AggLayer routes transfers over the AggLayer unified bridge. It currently serves the Bali pilot testnet chains — Bali PP (EVM chain ID `828282`, AggLayer rollup ID 82) and Bali FEP (EVM chain ID `858585`, AggLayer rollup ID 85) — which settle to the Sepolia testnet L1 (chain ID `11155111`). AggLayer routes require an explicit `bridgeProvider="AGGLAYER"` selection. + + +AggLayer support ships with the upcoming 0xtrails SDK release and is not yet available in the currently published version. + ```tsx - + ``` -- **ETA-driven waits**: the quote's completion estimate drives the SDK's receipt-polling window and the widget's slow-route warnings. AggLayer waits are raised to a per-direction corridor floor — 20 minutes for transfers entering from the L1, 3 hours for exits — and to 1.5× the quote's estimate when that is longer. A pre-commit banner appears when the estimate is 10 minutes or more. -- **Slow routes**: hops originating on the FEP chain (`85`) wait for an L1 global exit root change before they can be claimed, and can take 90 minutes or more. Typical completions are shorter — roughly 10–15 minutes for `82` → `85` and about 20 minutes for `85` → `82` — but budget for the slow path. -- **L1 data fee**: receipts on both corridors include an L1 data fee. The first claim of a token costs about 1.02M gas, a repeat ERC-20 claim about 228k, and an ETH claim about 150k. +Target the Bali chains by their EVM chain ID as shown above (828282 / 858585); the 82 / 85 numbers are AggLayer rollup IDs, not chain IDs. Sepolia (`11155111`) works as the L1 side of an AggLayer route. + +- **ETA-driven waits**: the quote's completion estimate drives the widget's slow-route warning and the SDK's receipt-polling window. Direction is decided by the quote's origin chain: an L1 origin (Sepolia) is an entry, and any L2 origin is an exit — including Bali-to-Bali hops. Entries are floored at 20 minutes; exits are floored at 3 hours, because exit claims wait for the L1's global exit root to advance. The estimate the quote and widget display is the quote's estimate raised to that floor, and the SDK polls for the receipt until 1.5× the estimate or the floor — whichever is longer. A 90-minute estimate from an L1 origin polls for 2h15m; the same estimate from an L2 origin polls for 3 hours. A pre-commit banner appears when the estimate reaches 10 minutes. +- **Slow routes**: every Bali-to-Bali hop originates on an L2, so both directions — Bali PP → Bali FEP and Bali FEP → Bali PP — are exits: the widget displays the 3-hour floor even when the raw route estimate is shorter (roughly 10–15 minutes for Bali PP → Bali FEP and about 20 minutes for Bali FEP → Bali PP). Exits can only be claimed after an L1 global exit root change, which is where the slow path comes from — budget for the 3-hour window the widget displays, not the raw estimate. +- **Claim gas**: the final claim step is paid by the user in ETH. Approximate costs: about 1.02M gas for the first claim of a token, about 228k for a repeat ERC-20 claim, and about 150k for an ETH claim (multiplied by the claim chain's gas price). ### Somnia (SOMNIA_EXCHANGE / SOMNIA_SWAP) From 036462dc281705a4388058a0ec9f68907dbbffe2 Mon Sep 17 00:00:00 2001 From: Arnau Bennassar Date: Mon, 19 Oct 2026 10:49:35 +0000 Subject: [PATCH 4/7] docs: correct FEP expansion, AGGLAYER coverage and exit-floor rationale (agglayer/issues#46) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - FEP is Full Execution Proof, not "front-end provers" (supported-chains type column) - AGGLAYER also serves Ethereum <-> Katana mainnet corridors (the routing table registers it for chains 1 and 747474), so both pages state the provider's general AggLayer corridor coverage instead of Bali-only scope - Exit-floor rationale qualified: the L1-GER-anchored wait is the FEP (85)-origin path (OP Succinct proof anchored to an L1 info-tree leaf); PP (82)-origin hops do not wait on it — the 3-hour floor is unchanged - Document the missing-estimate behavior: a quote with no estimate displays and polls the direction floor itself - Soften "require an explicit selection": AUTO only falls back to AGGLAYER last and a trustless route preference also selects it; mirror the qualifier in the routes table - Separate display (floored estimate) from polling (1.5x headroom) in the supported-chains note; bridge PP/FEP naming to the SDK's "Bali 82"/"Bali 85" --- resources/supported-chains.mdx | 8 ++++---- sdk/quote-providers.mdx | 8 +++++--- 2 files changed, 9 insertions(+), 7 deletions(-) diff --git a/resources/supported-chains.mdx b/resources/supported-chains.mdx index 2ffc7b4..bb13096 100644 --- a/resources/supported-chains.mdx +++ b/resources/supported-chains.mdx @@ -51,11 +51,11 @@ Trails supports the following testnet chains. The Bali pilot networks settle to | Chain | Chain ID | Type | Native Token | Status | |-------|----------|------|--------------|--------| | Sepolia | 11155111 | Ethereum testnet L1 | ETH | ✅ Supported | -| Bali PP | 828282 | AggLayer pessimistic proof | ETH | ✅ Pilot | -| Bali FEP | 858585 | AggLayer front-end provers (FEP) | ETH | ✅ Pilot | +| Bali PP ("Bali 82" in the SDK) | 828282 | AggLayer pessimistic proof | ETH | ✅ Pilot | +| Bali FEP ("Bali 85" in the SDK) | 858585 | AggLayer full execution proof (FEP) | ETH | ✅ Pilot | -The Bali chains are AggLayer pilot networks — rollup IDs 82 and 85; the table lists their EVM chain IDs. No public block explorer exists for either chain yet. AggLayer transfers display and poll the quote's completion estimate raised to a direction floor (20 minutes from an L1 origin, 3 hours from an L2 origin) with 1.5× headroom — see [AggLayer](/sdk/quote-providers#agglayer). +The Bali chains are AggLayer pilot networks — rollup IDs 82 and 85; the table lists their EVM chain IDs. No public block explorer exists for either chain yet. AggLayer transfers display the quote's completion estimate raised to a direction floor (20 minutes from an L1 origin, 3 hours from an L2 origin) and poll for up to 1.5× the estimate, never less than the floor — see [AggLayer](/sdk/quote-providers#agglayer). ## Stablecoin Details @@ -127,7 +127,7 @@ Trails routes transactions through the optimal liquidity source for each transfe | **LayerZero Transfer** | `LZ_TRANSFER` | Bridge | LayerZero Value Transfer API; explicit selection only | | **Open Intents Framework** | `OIF` | Bridge | Solver-filled cross-chain intents; explicit selection only | | **Gas.zip** | `GASZIP` | Bridge | Gas-optimized cross-chain routing | -| **AggLayer** | `AGGLAYER` | Bridge | AggLayer unified bridge; Bali pilot testnet chains (828282, 858585) | +| **AggLayer** | `AGGLAYER` | Bridge | AggLayer unified bridge; AggLayer corridors incl. the Bali pilot testnet chains (828282, 858585); explicit selection recommended (AUTO uses it only as a last resort) | | **LI.FI** | `LIFI` | Bridge / DEX aggregator | Aggregated cross-chain and same-chain routing | | **0x Protocol** | `ZEROX` | DEX aggregator | Best execution routing across multiple DEXs | | **SushiSwap** | `SUSHI` | DEX | On-chain swap routing with V3 concentrated liquidity | diff --git a/sdk/quote-providers.mdx b/sdk/quote-providers.mdx index 078ecb4..4132c30 100644 --- a/sdk/quote-providers.mdx +++ b/sdk/quote-providers.mdx @@ -179,7 +179,9 @@ Gas.zip is a gas-optimized routing provider that reduces the total gas cost of c ### AggLayer -AggLayer routes transfers over the AggLayer unified bridge. It currently serves the Bali pilot testnet chains — Bali PP (EVM chain ID `828282`, AggLayer rollup ID 82) and Bali FEP (EVM chain ID `858585`, AggLayer rollup ID 85) — which settle to the Sepolia testnet L1 (chain ID `11155111`). AggLayer routes require an explicit `bridgeProvider="AGGLAYER"` selection. +AggLayer routes transfers over the AggLayer unified bridge, which serves AggLayer-connected corridors, including Ethereum ↔ Katana mainnet. This section documents the Bali pilot testnet chains — Bali PP (EVM chain ID `828282`, AggLayer rollup ID 82) and Bali FEP (EVM chain ID `858585`, AggLayer rollup ID 85) — which settle to the Sepolia testnet L1 (chain ID `11155111`). + +An explicit selection is not required: AUTO only falls back to `AGGLAYER` as a last resort when no other provider can route a corridor the AggLayer bridge serves, and a trustless route preference also selects it deliberately. Pin `bridgeProvider="AGGLAYER"` to guarantee an AggLayer route. AggLayer support ships with the upcoming 0xtrails SDK release and is not yet available in the currently published version. @@ -196,8 +198,8 @@ AggLayer support ships with the upcoming 0xtrails SDK release and is not yet ava Target the Bali chains by their EVM chain ID as shown above (828282 / 858585); the 82 / 85 numbers are AggLayer rollup IDs, not chain IDs. Sepolia (`11155111`) works as the L1 side of an AggLayer route. -- **ETA-driven waits**: the quote's completion estimate drives the widget's slow-route warning and the SDK's receipt-polling window. Direction is decided by the quote's origin chain: an L1 origin (Sepolia) is an entry, and any L2 origin is an exit — including Bali-to-Bali hops. Entries are floored at 20 minutes; exits are floored at 3 hours, because exit claims wait for the L1's global exit root to advance. The estimate the quote and widget display is the quote's estimate raised to that floor, and the SDK polls for the receipt until 1.5× the estimate or the floor — whichever is longer. A 90-minute estimate from an L1 origin polls for 2h15m; the same estimate from an L2 origin polls for 3 hours. A pre-commit banner appears when the estimate reaches 10 minutes. -- **Slow routes**: every Bali-to-Bali hop originates on an L2, so both directions — Bali PP → Bali FEP and Bali FEP → Bali PP — are exits: the widget displays the 3-hour floor even when the raw route estimate is shorter (roughly 10–15 minutes for Bali PP → Bali FEP and about 20 minutes for Bali FEP → Bali PP). Exits can only be claimed after an L1 global exit root change, which is where the slow path comes from — budget for the 3-hour window the widget displays, not the raw estimate. +- **ETA-driven waits**: the quote's completion estimate drives the widget's slow-route warning and the SDK's receipt-polling window. Direction is decided by the quote's origin chain: an L1 origin (Sepolia) is an entry, and any L2 origin is an exit — including Bali-to-Bali hops. Entries are floored at 20 minutes; exits are floored at 3 hours: exit claims — in particular from the FEP chain, whose proofs anchor to an L1 global exit root change — can be blocked until the L1's global exit root advances (roughly hourly on a quiet testnet L1). The estimate the quote and widget display is the quote's estimate raised to that floor, and the SDK polls for the receipt until 1.5× the estimate or the floor — whichever is longer. A quote that carries no completion estimate displays and polls the direction floor itself (20 minutes from an L1 origin, 3 hours from an L2 origin). A 90-minute estimate from an L1 origin polls for 2h15m; the same estimate from an L2 origin polls for 3 hours. A pre-commit banner appears when the estimate reaches 10 minutes. +- **Slow routes**: every Bali-to-Bali hop originates on an L2, so both directions — Bali PP → Bali FEP and Bali FEP → Bali PP — are exits: the widget displays the 3-hour floor even when the raw route estimate is shorter (roughly 10–15 minutes for Bali PP → Bali FEP and about 20 minutes for Bali FEP → Bali PP). The FEP side is where the wait comes from: an FEP-origin claim waits for its OP Succinct proof, which anchors to a new L1 info-tree leaf that only appears when the L1's global exit root changes (roughly hourly on a quiet Sepolia); PP-origin hops do not wait on that anchor. Budget for the 3-hour window the widget displays, not the raw estimate. - **Claim gas**: the final claim step is paid by the user in ETH. Approximate costs: about 1.02M gas for the first claim of a token, about 228k for a repeat ERC-20 claim, and about 150k for an ETH claim (multiplied by the claim chain's gas price). ### Somnia (SOMNIA_EXCHANGE / SOMNIA_SWAP) From 136ce3cf81b4989569783e994f5f83f7b3fe11af Mon Sep 17 00:00:00 2001 From: Arnau Bennassar Date: Mon, 19 Oct 2026 21:16:07 +0000 Subject: [PATCH 5/7] docs(agglayer): correct claim sponsorship and ETA references --- resources/supported-chains.mdx | 4 ++-- sdk/quote-providers.mdx | 5 +++-- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/resources/supported-chains.mdx b/resources/supported-chains.mdx index bb13096..34185f8 100644 --- a/resources/supported-chains.mdx +++ b/resources/supported-chains.mdx @@ -55,7 +55,7 @@ Trails supports the following testnet chains. The Bali pilot networks settle to | Bali FEP ("Bali 85" in the SDK) | 858585 | AggLayer full execution proof (FEP) | ETH | ✅ Pilot | -The Bali chains are AggLayer pilot networks — rollup IDs 82 and 85; the table lists their EVM chain IDs. No public block explorer exists for either chain yet. AggLayer transfers display the quote's completion estimate raised to a direction floor (20 minutes from an L1 origin, 3 hours from an L2 origin) and poll for up to 1.5× the estimate, never less than the floor — see [AggLayer](/sdk/quote-providers#agglayer). +The Bali chains are AggLayer pilot networks — rollup IDs 82 and 85; the table lists their EVM chain IDs. No public block explorer exists for either chain yet. For how AggLayer transfer times are estimated and polled, see [AggLayer](/sdk/quote-providers#agglayer). ## Stablecoin Details @@ -127,7 +127,7 @@ Trails routes transactions through the optimal liquidity source for each transfe | **LayerZero Transfer** | `LZ_TRANSFER` | Bridge | LayerZero Value Transfer API; explicit selection only | | **Open Intents Framework** | `OIF` | Bridge | Solver-filled cross-chain intents; explicit selection only | | **Gas.zip** | `GASZIP` | Bridge | Gas-optimized cross-chain routing | -| **AggLayer** | `AGGLAYER` | Bridge | AggLayer unified bridge; AggLayer corridors incl. the Bali pilot testnet chains (828282, 858585); explicit selection recommended (AUTO uses it only as a last resort) | +| **AggLayer** | `AGGLAYER` | Bridge | AggLayer unified bridge; AggLayer corridors incl. the Bali pilot testnet chains (828282, 858585); see [AggLayer](/sdk/quote-providers#agglayer) for when AUTO selects it | | **LI.FI** | `LIFI` | Bridge / DEX aggregator | Aggregated cross-chain and same-chain routing | | **0x Protocol** | `ZEROX` | DEX aggregator | Best execution routing across multiple DEXs | | **SushiSwap** | `SUSHI` | DEX | On-chain swap routing with V3 concentrated liquidity | diff --git a/sdk/quote-providers.mdx b/sdk/quote-providers.mdx index 4132c30..76691dd 100644 --- a/sdk/quote-providers.mdx +++ b/sdk/quote-providers.mdx @@ -183,8 +183,9 @@ AggLayer routes transfers over the AggLayer unified bridge, which serves AggLaye An explicit selection is not required: AUTO only falls back to `AGGLAYER` as a last resort when no other provider can route a corridor the AggLayer bridge serves, and a trustless route preference also selects it deliberately. Pin `bridgeProvider="AGGLAYER"` to guarantee an AggLayer route. +{/* Remove this note once an 0xtrails release containing 0xsequence/trails#1297 is published. */} -AggLayer support ships with the upcoming 0xtrails SDK release and is not yet available in the currently published version. +AggLayer support is not available in `0xtrails@0.19.1` or earlier. It ships in the first release that includes [0xsequence/trails#1297](https://github.com/0xsequence/trails/pull/1297). ```tsx @@ -200,7 +201,7 @@ Target the Bali chains by their EVM chain ID as shown above (828282 / 858585); t - **ETA-driven waits**: the quote's completion estimate drives the widget's slow-route warning and the SDK's receipt-polling window. Direction is decided by the quote's origin chain: an L1 origin (Sepolia) is an entry, and any L2 origin is an exit — including Bali-to-Bali hops. Entries are floored at 20 minutes; exits are floored at 3 hours: exit claims — in particular from the FEP chain, whose proofs anchor to an L1 global exit root change — can be blocked until the L1's global exit root advances (roughly hourly on a quiet testnet L1). The estimate the quote and widget display is the quote's estimate raised to that floor, and the SDK polls for the receipt until 1.5× the estimate or the floor — whichever is longer. A quote that carries no completion estimate displays and polls the direction floor itself (20 minutes from an L1 origin, 3 hours from an L2 origin). A 90-minute estimate from an L1 origin polls for 2h15m; the same estimate from an L2 origin polls for 3 hours. A pre-commit banner appears when the estimate reaches 10 minutes. - **Slow routes**: every Bali-to-Bali hop originates on an L2, so both directions — Bali PP → Bali FEP and Bali FEP → Bali PP — are exits: the widget displays the 3-hour floor even when the raw route estimate is shorter (roughly 10–15 minutes for Bali PP → Bali FEP and about 20 minutes for Bali FEP → Bali PP). The FEP side is where the wait comes from: an FEP-origin claim waits for its OP Succinct proof, which anchors to a new L1 info-tree leaf that only appears when the L1's global exit root changes (roughly hourly on a quiet Sepolia); PP-origin hops do not wait on that anchor. Budget for the 3-hour window the widget displays, not the raw estimate. -- **Claim gas**: the final claim step is paid by the user in ETH. Approximate costs: about 1.02M gas for the first claim of a token, about 228k for a repeat ERC-20 claim, and about 150k for an ETH claim (multiplied by the claim chain's gas price). +- **Claim gas**: you do not send or pay for the claim transaction yourself. Claims into an L2 (such as the Bali chains) are executed automatically by the chain operator's AggKit; claims into an ecosystem's L1 (such as Sepolia) are sent by Trails. The cost of the claim is included in the quoted fee, denominated in the route token, so there is no separate ETH payment at claim time. The fee is based on approximate claim gas: about 1.02M gas for the first claim of a token, about 228k for a repeat ERC-20 claim, and about 150k for an ETH claim (multiplied by the claim chain's gas price). ### Somnia (SOMNIA_EXCHANGE / SOMNIA_SWAP) From 6c904763346fa166cd7c655032c753cba79fe13b Mon Sep 17 00:00:00 2001 From: Arnau Bennassar Date: Tue, 20 Oct 2026 09:24:59 +0000 Subject: [PATCH 6/7] docs(agglayer): align polling windows with the API budgets --- sdk/quote-providers.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sdk/quote-providers.mdx b/sdk/quote-providers.mdx index 76691dd..559c799 100644 --- a/sdk/quote-providers.mdx +++ b/sdk/quote-providers.mdx @@ -199,8 +199,8 @@ AggLayer support is not available in `0xtrails@0.19.1` or earlier. It ships in t Target the Bali chains by their EVM chain ID as shown above (828282 / 858585); the 82 / 85 numbers are AggLayer rollup IDs, not chain IDs. Sepolia (`11155111`) works as the L1 side of an AggLayer route. -- **ETA-driven waits**: the quote's completion estimate drives the widget's slow-route warning and the SDK's receipt-polling window. Direction is decided by the quote's origin chain: an L1 origin (Sepolia) is an entry, and any L2 origin is an exit — including Bali-to-Bali hops. Entries are floored at 20 minutes; exits are floored at 3 hours: exit claims — in particular from the FEP chain, whose proofs anchor to an L1 global exit root change — can be blocked until the L1's global exit root advances (roughly hourly on a quiet testnet L1). The estimate the quote and widget display is the quote's estimate raised to that floor, and the SDK polls for the receipt until 1.5× the estimate or the floor — whichever is longer. A quote that carries no completion estimate displays and polls the direction floor itself (20 minutes from an L1 origin, 3 hours from an L2 origin). A 90-minute estimate from an L1 origin polls for 2h15m; the same estimate from an L2 origin polls for 3 hours. A pre-commit banner appears when the estimate reaches 10 minutes. -- **Slow routes**: every Bali-to-Bali hop originates on an L2, so both directions — Bali PP → Bali FEP and Bali FEP → Bali PP — are exits: the widget displays the 3-hour floor even when the raw route estimate is shorter (roughly 10–15 minutes for Bali PP → Bali FEP and about 20 minutes for Bali FEP → Bali PP). The FEP side is where the wait comes from: an FEP-origin claim waits for its OP Succinct proof, which anchors to a new L1 info-tree leaf that only appears when the L1's global exit root changes (roughly hourly on a quiet Sepolia); PP-origin hops do not wait on that anchor. Budget for the 3-hour window the widget displays, not the raw estimate. +- **ETA-driven waits**: the quote's completion estimate drives the widget's slow-route warning and the SDK's receipt-polling window. Direction is decided by the quote's origin chain: an L1 origin (Sepolia) is an entry, and any L2 origin is an exit — including Bali-to-Bali hops. Entries are floored at 2 hours; exits are floored at 24 hours: exit claims — in particular from the FEP chain, whose proofs anchor to an L1 global exit root change — can be blocked until the L1's global exit root advances (roughly hourly on a quiet testnet L1). The estimate the quote and widget display is the quote's estimate raised to that floor, and the SDK polls for the receipt until 1.5× the estimate or the floor — whichever is longer, never beyond a 24-hour ceiling. A quote that carries no completion estimate displays and polls the direction floor itself (2 hours from an L1 origin, 24 hours from an L2 origin). A 90-minute estimate from an L1 origin polls for 2h15m; the same estimate from an L2 origin polls for 24 hours. A pre-commit banner appears when the estimate reaches 10 minutes. +- **Slow routes**: every Bali-to-Bali hop originates on an L2, so both directions — Bali PP → Bali FEP and Bali FEP → Bali PP — are exits: the widget displays the 24-hour floor even when the raw route estimate is shorter (roughly 10–15 minutes for Bali PP → Bali FEP and about 20 minutes for Bali FEP → Bali PP). The FEP side is where the wait comes from: an FEP-origin claim waits for its OP Succinct proof, which anchors to a new L1 info-tree leaf that only appears when the L1's global exit root changes (roughly hourly on a quiet Sepolia); PP-origin hops do not wait on that anchor. Budget for the 24-hour window the widget displays, not the raw estimate. - **Claim gas**: you do not send or pay for the claim transaction yourself. Claims into an L2 (such as the Bali chains) are executed automatically by the chain operator's AggKit; claims into an ecosystem's L1 (such as Sepolia) are sent by Trails. The cost of the claim is included in the quoted fee, denominated in the route token, so there is no separate ETH payment at claim time. The fee is based on approximate claim gas: about 1.02M gas for the first claim of a token, about 228k for a repeat ERC-20 claim, and about 150k for an ETH claim (multiplied by the claim chain's gas price). ### Somnia (SOMNIA_EXCHANGE / SOMNIA_SWAP) From a9ae24f54a0803f1b3812ab079d18dc45f235f40 Mon Sep 17 00:00:00 2001 From: Arnau Bennassar Date: Tue, 20 Oct 2026 17:13:08 +0000 Subject: [PATCH 7/7] docs(agglayer): split displayed floors from polling floors and fix claim executor --- sdk/quote-providers.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/sdk/quote-providers.mdx b/sdk/quote-providers.mdx index 559c799..13fd29c 100644 --- a/sdk/quote-providers.mdx +++ b/sdk/quote-providers.mdx @@ -199,9 +199,9 @@ AggLayer support is not available in `0xtrails@0.19.1` or earlier. It ships in t Target the Bali chains by their EVM chain ID as shown above (828282 / 858585); the 82 / 85 numbers are AggLayer rollup IDs, not chain IDs. Sepolia (`11155111`) works as the L1 side of an AggLayer route. -- **ETA-driven waits**: the quote's completion estimate drives the widget's slow-route warning and the SDK's receipt-polling window. Direction is decided by the quote's origin chain: an L1 origin (Sepolia) is an entry, and any L2 origin is an exit — including Bali-to-Bali hops. Entries are floored at 2 hours; exits are floored at 24 hours: exit claims — in particular from the FEP chain, whose proofs anchor to an L1 global exit root change — can be blocked until the L1's global exit root advances (roughly hourly on a quiet testnet L1). The estimate the quote and widget display is the quote's estimate raised to that floor, and the SDK polls for the receipt until 1.5× the estimate or the floor — whichever is longer, never beyond a 24-hour ceiling. A quote that carries no completion estimate displays and polls the direction floor itself (2 hours from an L1 origin, 24 hours from an L2 origin). A 90-minute estimate from an L1 origin polls for 2h15m; the same estimate from an L2 origin polls for 24 hours. A pre-commit banner appears when the estimate reaches 10 minutes. -- **Slow routes**: every Bali-to-Bali hop originates on an L2, so both directions — Bali PP → Bali FEP and Bali FEP → Bali PP — are exits: the widget displays the 24-hour floor even when the raw route estimate is shorter (roughly 10–15 minutes for Bali PP → Bali FEP and about 20 minutes for Bali FEP → Bali PP). The FEP side is where the wait comes from: an FEP-origin claim waits for its OP Succinct proof, which anchors to a new L1 info-tree leaf that only appears when the L1's global exit root changes (roughly hourly on a quiet Sepolia); PP-origin hops do not wait on that anchor. Budget for the 24-hour window the widget displays, not the raw estimate. -- **Claim gas**: you do not send or pay for the claim transaction yourself. Claims into an L2 (such as the Bali chains) are executed automatically by the chain operator's AggKit; claims into an ecosystem's L1 (such as Sepolia) are sent by Trails. The cost of the claim is included in the quoted fee, denominated in the route token, so there is no separate ETH payment at claim time. The fee is based on approximate claim gas: about 1.02M gas for the first claim of a token, about 228k for a repeat ERC-20 claim, and about 150k for an ETH claim (multiplied by the claim chain's gas price). +- **ETA-driven waits**: the quote's completion estimate drives the widget's slow-route warning and the SDK's receipt-polling window. Direction is decided by the quote's origin chain: an L1 origin (Sepolia) is an entry, and any L2 origin is an exit — including Bali-to-Bali hops. The quote and widget display the quote's estimate raised to an expected-duration floor of 20 minutes for entries and 3 hours for exits: exit claims — in particular from the FEP chain, whose proofs anchor to an L1 global exit root change — can be blocked until the L1's global exit root advances (roughly hourly on a quiet testnet L1). The widget's "taking longer than expected" warning is due at 1.5× the estimate, never earlier than that floor. The SDK keeps polling for the receipt longer, matching the backend's own budgets: until 1.5× the estimate or 2 hours (L1 origin) / 24 hours (L2 origin), whichever is longer, never beyond a 24-hour ceiling. A quote that carries no completion estimate displays the direction floor itself (20 minutes from an L1 origin, 3 hours from an L2 origin) and polls for the 2-hour or 24-hour floor. A 90-minute estimate from an L1 origin is displayed as 90 minutes, warns at 2h15m and polls for 2h15m; the same estimate from an L2 origin is displayed as 3 hours, warns at 3 hours and polls for 24 hours. A pre-commit banner appears when the estimate reaches 10 minutes. +- **Slow routes**: every Bali-to-Bali hop originates on an L2, so both directions — Bali PP → Bali FEP and Bali FEP → Bali PP — are exits: the widget displays the 3-hour floor even when the raw route estimate is shorter (roughly 10–15 minutes for Bali PP → Bali FEP and about 20 minutes for Bali FEP → Bali PP). The FEP side is where the wait comes from: an FEP-origin claim waits for its OP Succinct proof, which anchors to a new L1 info-tree leaf that only appears when the L1's global exit root changes (roughly hourly on a quiet Sepolia); PP-origin hops do not wait on that anchor. Budget for the 3-hour window the widget displays, not the raw estimate; the SDK keeps polling for up to 24 hours before it reports a timeout. +- **Claim gas**: you do not send or pay for the claim transaction yourself; Trails executes every claim, whether the destination is an L2 (such as the Bali chains) or an ecosystem's L1 (such as Sepolia). The claim gas is included in the quoted fee, denominated in the route token, so there is no separate ETH payment at claim time. The fee is based on approximate claim gas: about 1.02M gas for the first claim of a token, about 228k for a repeat ERC-20 claim, and about 150k for an ETH claim (multiplied by the claim chain's gas price). ### Somnia (SOMNIA_EXCHANGE / SOMNIA_SWAP)