diff --git a/.github/styles/config/vocabularies/Arcana/accept.txt b/.github/styles/config/vocabularies/Arcana/accept.txt index 8a6793ba..20cc532c 100644 --- a/.github/styles/config/vocabularies/Arcana/accept.txt +++ b/.github/styles/config/vocabularies/Arcana/accept.txt @@ -1006,6 +1006,7 @@ passwordless Passwordless PasswordlessOptions Peaq +Pectra performant permissioned Permissioned diff --git a/docs/concepts/ca/chain-abstraction.md b/docs/concepts/ca/chain-abstraction.md index 398a3b6f..8b680da4 100644 --- a/docs/concepts/ca/chain-abstraction.md +++ b/docs/concepts/ca/chain-abstraction.md @@ -9,3 +9,7 @@ arcana: # Chain Abstraction {% include "./text-snippets/ca/what_is_ca.md" %} + +## Cross-Chain Chain Abstraction (CCA) + +{% include "./text-snippets/ca/cross_chain.md" %} diff --git a/docs/concepts/ca/unified-balance.md b/docs/concepts/ca/unified-balance.md index 3a90e1bd..2ebfbbe2 100644 --- a/docs/concepts/ca/unified-balance.md +++ b/docs/concepts/ca/unified-balance.md @@ -8,4 +8,5 @@ arcana: # Unified balance -{% include "./text-snippets/ca/unified_balance.md" %} \ No newline at end of file +{% include "./text-snippets/ca/unified_balance.md" %} + diff --git a/docs/concepts/ca/unified-xcs-balance.md b/docs/concepts/ca/unified-xcs-balance.md new file mode 100644 index 00000000..5d505a60 --- /dev/null +++ b/docs/concepts/ca/unified-xcs-balance.md @@ -0,0 +1,11 @@ +--- +alias: concept-xcs +title: 'Unified Cross-Chain Swap Balance' +description: 'What does unified cross-chain swap balance mean in Arcana Chain Abstraction context?' +arcana: + root_rel_path: .. +--- + +# Cross-Chain Swap (XCS) + +{% include "./text-snippets/ca/xcs_feature.md" %} \ No newline at end of file diff --git a/docs/img/an_ca_xcs_feature.webp b/docs/img/an_ca_xcs_feature.webp new file mode 100644 index 00000000..289702cd Binary files /dev/null and b/docs/img/an_ca_xcs_feature.webp differ diff --git a/docs/quick-start/.ca-wagmi-quick-start.md.swp b/docs/quick-start/.ca-wagmi-quick-start.md.swp new file mode 100644 index 00000000..9d992755 Binary files /dev/null and b/docs/quick-start/.ca-wagmi-quick-start.md.swp differ diff --git a/docs/web3-stack/ca_stack.md b/docs/web3-stack/ca_stack.md index f3f47824..a3650590 100644 --- a/docs/web3-stack/ca_stack.md +++ b/docs/web3-stack/ca_stack.md @@ -18,165 +18,4 @@ To execute a chain-abstracted transaction, you need enough unified balance of th {% include "./text-snippets/ca_token_qualifier.md" %} -### Ethereum - -=== "Mainnet" - - | Tokens | Coral | - | :--- | :---| - | ETH | ✅ | - | USDC | ✅ | - | USDT | ✅ | - -=== "Sepolia" - - | Tokens | Folly | - | :--- | :---| - | ETH | ✅ | - | USDC | ✅ | - -### Optimism - -=== "Mainnet" - - | Tokens | Coral | - | :--- | :--- | - | ETH | ✅ | - | USDC | ✅ | - | USDT | ✅ | - -=== "OP Sepolia" - - | Tokens | Folly | - | :--- | :--- | - | ETH | ✅ | - | USDC | ✅ | - | USDT | ✅ | - -### BSC - -=== "Mainnet" - - | Tokens | Coral | - | :--- | :--- | - | ETH | ✅ | - | USDC | ✅ | - | USDT | ✅ | - | BNB | ✅ | - -### Polygon - -=== "Mainnet" - - | Tokens | Coral - | :--- | :--- | - | USDC | ✅ | - | USDT | ✅ | - | POL | ✅ | - -=== "Polygon Amoy" - - | Tokens | Folly | - | :--- | :--- | - | USDC | ✅ | - | POL | ✅ | - - - - -### Kaia - -=== "Mainnet" - - | Tokens | Coral | - | :--- | :--- | - | USDT | ✅ | - | KAIA | ✅ | - -### Base - -=== "Mainnet" - - | Tokens | Coral | - | :--- | :--- | - | ETH | ✅ | - | USDC | ✅ | - | USDT | ✅ | - -=== "Base Sepolia" - - | Tokens | Folly | - | :--- | :--- | - | ETH | ✅ | - | USDC | ✅ | - -### Fuel - -=== "Mainnet" - - | Tokens | Coral | - | :--- | :--- | - | ETH | ✅ | - | USDC | ✅ | - | USDT | ✅ | - -{% include "./text-snippets/warn_no_fuel_support_ca_wagmi.md" %} - -### Arbitrum - -=== "Mainnet" - - | Tokens | Coral | - | :--- | :--- | - | ETH | ✅ | - | USDC | ✅ | - | USDT | ✅ | - -=== "Arbitrum Sepolia" - - | Tokens | Folly | - | :--- | :---| - | ETH | ✅ | - | USDC | ✅ | - | USDT | ✅ | - -### Avalanche - -=== "Mainnet" - - | Tokens | Coral | - | :--- | :--- | - | USDC | ✅ | - | USDT | ✅ | - | AVAX | ✅ | - -### Sophon - -=== "Mainnet" - - | Tokens | Coral | - | :--- | :--- | - | ETH | ✅ | - | USDC | ✅ | - | USDT | ✅ | - | SOPH | ✅ | - -### Scroll - -=== "Mainnet" - - | Tokens | Coral | - | :--- | :--- | - | ETH | ✅ | - | USDC | ✅ | - | USDT | ✅ | +{% include "./text-snippets/ca/generated_chainlist.md" %} diff --git a/docs/web3-stack/ca_wallet_stack.md b/docs/web3-stack/ca_wallet_stack.md index 512f396c..b7ce4e34 100644 --- a/docs/web3-stack/ca_wallet_stack.md +++ b/docs/web3-stack/ca_wallet_stack.md @@ -24,163 +24,4 @@ To try unified balance and chain abstracted transactions, connect the [standalon {% include "./text-snippets/ca_token_qualifier.md" %} -### Ethereum - -=== "Mainnet" - - | Tokens | Coral | - | :--- | :---| - | ETH | ✅ | - | USDC | ✅ | - | USDT | ✅ | - -=== "Sepolia" - - | Tokens | Folly | - | :--- | :---| - | ETH | ✅ | - | USDC | ✅ | - -### Optimism - -=== "Mainnet" - - | Tokens | Coral | - | :--- | :--- | - | ETH | ✅ | - | USDC | ✅ | - | USDT | ✅ | - -=== "OP Sepolia" - - | Tokens | Folly | - | :--- | :--- | - | ETH | ✅ | - | USDC | ✅ | - | USDT | ✅ | - -### BSC - -=== "Mainnet" - - | Tokens | Coral | - | :--- | :--- | - | ETH | ✅ | - | USDC | ✅ | - | USDT | ✅ | - | BNB | ✅ | - -### Polygon - -=== "Mainnet" - - | Tokens | Coral - | :--- | :--- | - | USDC | ✅ | - | USDT | ✅ | - | POL | ✅ | - -=== "Polygon Amoy" - - | Tokens | Folly | - | :--- | :--- | - | USDC | ✅ | - | POL | ✅ | - - - - -### Kaia - -=== "Mainnet" - - | Tokens | Coral | - | :--- | :--- | - | USDT | ✅ | - | KAIA | ✅ | - -### Base - -=== "Mainnet" - - | Tokens | Coral | - | :--- | :--- | - | ETH | ✅ | - | USDC | ✅ | - | USDT | ✅ | - -=== "Base Sepolia" - - | Tokens | Folly | - | :--- | :--- | - | ETH | ✅ | - | USDC | ✅ | - -### Fuel - -=== "Mainnet" - - | Tokens | Coral | - | :--- | :--- | - | ETH | ✅ | - | USDC | ✅ | - | USDT | ✅ | - -### Arbitrum - -=== "Mainnet" - - | Tokens | Coral | - | :--- | :--- | - | ETH | ✅ | - | USDC | ✅ | - | USDT | ✅ | - -=== "Arbitrum Sepolia" - - | Tokens | Folly | - | :--- | :---| - | ETH | ✅ | - | USDC | ✅ | - | USDT | ✅ | - -### Avalanche - -=== "Mainnet" - - | Tokens | Coral | - | :--- | :--- | - | USDC | ✅ | - | USDT | ✅ | - | AVAX | ✅ | - -### Sophon - -=== "Mainnet" - - | Tokens | Coral | - | :--- | :--- | - | ETH | ✅ | - | USDC | ✅ | - | USDT | ✅ | - | SOPH | ✅ | - -### Scroll - -=== "Mainnet" - - | Tokens | Coral | - | :--- | :--- | - | ETH | ✅ | - | USDC | ✅ | - | USDT | ✅ | +{% include "./text-snippets/ca/generated_chainlist.md" %} \ No newline at end of file diff --git a/includes/text-snippets/ca/cross_chain.md b/includes/text-snippets/ca/cross_chain.md new file mode 100644 index 00000000..b1e765b8 --- /dev/null +++ b/includes/text-snippets/ca/cross_chain.md @@ -0,0 +1,21 @@ +[[concept-ca|Chain abstraction]] lets users spend *a single token type (like USDT)* across source chains using a [[concept-unified-balance|unified balance]]. They can then use that balance on any destination chain—still as USDT. + +Cross-chain Chain Abstraction (CCA) takes it further. Users can now *combine multiple token types (like USDT, USDC)* into one unified balance across chains—and spend it as any supported token (USDT, USDC, etc.) on any destination chain. + +The cross-chain chain abstraction is atomic in nature. It involves multiple source chains and token types and batches transactions. If any one sub-transaction fails, the entire cross-chain transaction fails. + +Cross-chain CA transactions do not have any overheads as compared to the basic chain abstracted transactions. These may be marginally faster than the basic chain abstracted transactions (single token type). + +??? an-note "Pectra Support" + + By default, Cross-Chain Abstraction (CCA) kicks in automatically for transactions between source chains that support Pectra. + + If any source chain doesn’t support Pectra, the SDK falls back to basic chain abstraction. This means users can use unified token balance to spend only a single unified token type from the source chains. + + The SDK smartly picks between CCA and base chain abstraction based on the source chains in the transaction and their Pectra support. No extra setup is needed by Web3 apps or users. + +??? an-tip "About Refunds" + + If a cross-chain CA transaction fails, the user gets a refund equal to the total deposits collected from their EOA across all source chains. + + Even if the deposits involved multiple token types, the refund is always in USDC. diff --git a/includes/text-snippets/ca/generated_chainlist.md b/includes/text-snippets/ca/generated_chainlist.md new file mode 100644 index 00000000..36e995cf --- /dev/null +++ b/includes/text-snippets/ca/generated_chainlist.md @@ -0,0 +1,182 @@ +!!! an-note "Unified Balance (XCS)" + + [[concept-xcs|Cross-Chain Support (XCS)]] enhances unified balance by allowing users to spend any supported token (e.g., USDT, USDC) from any source chain on any destination chain—provided the chain and token contract support the EIP-2612 `permit` function. + + For chains or tokens without `permit/EIP-2612`, the protocol reverts to the basic unified balance, which only combines the same token type across source chains. + +### Ethereum + +=== "Mainnet" + + | Coral | Unified Balance | Unified Balance (XCS) | + | :--- | :---| :---| + | ETH | ✅ | ❌ | + | USDC | ✅ | ✅ | + | USDT | ✅ | ❌ | + | DAI | ❓ | ✅ | + +=== "Sepolia" + + | Folly | Unified Balance | Unified Balance (XCS) | + | :--- | :--- | :--- | + | ETH | ✅ | ❌ | + | USDC | ✅ | ❓ | + +### Optimism + +=== "Mainnet" + + | Coral | Unified Balance | Unified Balance (XCS) | + | :--- | :--- | :--- | + | ETH | ✅ | ❌ | + | USDC | ✅ | ✅ | + | USDT | ✅ | ❌ | + | DAI | ❓ | ✅ | + +=== "OP Sepolia" + + | Folly | Unified Balance | Unified Balance (XCS) | + | :--- | :--- | :--- | + | ETH | ✅ | ❌ | + | USDC | ✅ | ❓ | + | USDT | ✅ | ❌ | + | DAI | ❓ | ✅ | + +### BSC + +=== "Mainnet" + + | Coral | Unified Balance | Unified Balance (XCS) | + | :--- | :--- | :--- | + | ETH | ✅ | ❌ | + | USDC | ✅ | ❌ | + | USDT | ✅ | ❌ | + | BNB | ✅ | ❌ | + +### Polygon + +!!! an-note "Polygon EMT, Polygon DAI" + + In the case of Polygon, the XCS feature uses `Polygon EMT` or `Polygon DAI` as the intermediary token for swaps. + +=== "Mainnet" + + | Coral | Unified Balance | Unified Balance (XCS) | + | :--- | :--- | :--- | + | USDC | ✅ | ✅ | + | USDT | ✅ | ✅ | + | POL | ✅ | ❌ | + | WETH | ❓ | ✅ | + | DAI | ❓ | ✅ | + +=== "Polygon Amoy" + + | Folly | Unified Balance | Unified Balance (XCS) | + | :--- | :--- | :--- | + | USDC | ✅ | ❌ | + | POL | ✅ | ❌ | + + + + +### Kaia + +=== "Mainnet" + + | Coral | Unified Balance | Unified Balance (XCS) | + | :--- | :--- | :--- | + | USDT | ✅ | ✅ | + | KAIA | ✅ | ❌ | + +### Base + +=== "Mainnet" + + | Coral | Unified Balance | Unified Balance (XCS) | + | :--- | :--- | :--- | + | ETH | ✅ | ❌ | + | USDC | ✅ | ✅ | + | USDT | ✅ | ❌ | + | WETH | ❓ | ❌ | + +=== "Base Sepolia" + + | Folly | Unified Balance | Unified Balance (XCS) | + | :--- | :--- | :--- | + | ETH | ✅ | ❌ | + | USDC | ✅ | ❌ | + +### Fuel + +=== "Mainnet" + + | Coral | Unified Balance | Unified Balance (XCS) | + | :--- | :--- | :--- | + | ETH | ✅ | ❌ | + | USDC | ✅ | ❌ | + | USDT | ✅ | ❌ | + +{% include "./text-snippets/warn_no_fuel_support_ca_wagmi.md" %} + +### Arbitrum + +=== "Mainnet" + + | Coral | Unified Balance | Unified Balance (XCS) | + | :--- | :--- | :--- | + | ETH | ✅ | ❌ | + | USDC | ✅ | ✅ | + | USDT | ✅ | ✅ | + | WETH | ❓ | ✅ | + | DAI | ❓ |✅ | + +=== "Arbitrum Sepolia" + + | Folly | Unified Balance | Unified Balance (XCS) | + | :--- | :---| :--- | + | ETH | ✅ | ❌ | + | USDC | ✅ | ❌ | + | USDT | ✅ | ❌ | + +### Avalanche + +=== "Mainnet" + + | Coral | Unified Balance | Unified Balance (XCS) | + | :--- | :--- | :--- | + | USDC | ✅ | ✅ | + | USDT | ✅ | ✅ | + | AVAX | ✅ | ❌ | + | DAI | ❓ | ❌ | + +### Sophon + +=== "Mainnet" + + | Coral | Unified Balance | Unified Balance (XCS) | + | :--- | :--- | :--- | + | ETH | ✅ | ❓ | + | USDC | ✅ | ❓ | + | USDT | ✅ | ❓ | + | SOPH | ✅ | ❓ | + +### Scroll + +=== "Mainnet" + + | Coral | Unified Balance | Unified Balance (XCS) | + | :--- | :--- | :--- | + | ETH | ✅ | ❌ | + | USDC | ✅ | ✅ | + | USDT | ✅ | ✅ | + | WETH | ❓ |✅ | diff --git a/includes/text-snippets/ca/unified_balance.md b/includes/text-snippets/ca/unified_balance.md index 6c210812..a79f139e 100644 --- a/includes/text-snippets/ca/unified_balance.md +++ b/includes/text-snippets/ca/unified_balance.md @@ -1,22 +1,42 @@ -Unified balance shows all the liquidity in a user's EOA account across multiple chains in one view. It lets users transact seamlessly on any chain without needing bridges or pre-provisioning gas for token swaps. Chain abstraction handles all the complexity involved in a cross-chain transaction while enabling better UX through a single intent approval. +Unified balance shows the total liquidity in a user's EOA account. It +combines the token balance across multiple chains. This lets users spend +the available liquidity on any destination chain via chain +abstracted transactions. -For instance, let us take the case where a user intends to spend 18 USDC on Scroll and does not have any balance on Scroll. +No bridges or pre-provisioned gas are needed. All cross-chain complexity is handled behind the scenes. Users approve their intent to spend just once for a seamless experience. -* Optimism: 0.1 ETH, O USDT, 0 USDC -* Arbitrum: 0 ETH, 12 USDT, 0 USDC -* Base: 0 ETH, 10 USDT, 0 USDC -* Scroll: 0 ETH, 0 USDT, 0 USDC +!!! an-example "Example" -To spend 18 USDC on Scroll (destination chain) with the given liquidity fragmentation, it would typically require multiple clicks and steps for swapping or bridging different assets available on the source chains, so that user can convert the assets to the desired token balance on Scroll. + Consider a wallet balance: + + - *Optimism:* 0.1 ETH, 0 USDT, 0 USDC + - *Arbitrum:* 0 ETH, 12 USDT, 0 USDC + - *Base:* 0 ETH, 10 USDT, 0 USDC + - *Scroll:* 0 ETH, 0 USDT, 0 USDC -Through chain abstraction and ability to swap cross-chain, users have the convenience to view the consolidated token balance across supported tokens and chains. This simplifies the process of sending 18 USDC on Scroll, as users can sign the intent without the need for bridging, swapping, or considering the optimal routes. + With no unified balance or chain abstraction, user *cannot spend any USDT on Scroll* unless + they use a bridge to convert tokens. -The cross-chain swap enables users to: + With basic unified balance and chain abstracted transaction, user **can spend 18 USDT on Scroll**. -- Spend assets on any destination chain without prior liquidity. -- Collate payable amount by combining multiple supported assets across source chains to address liquidity fragmentation. + | Intent | No Unified Balance / CA | Unified Balance | + |:---|:---|:---| + | Spend 18 **USDT** on Scroll | ❌ | ✅ |
With CA -
Single chain liquidity vs. Unified Balance with Chain Abstraction
-
\ No newline at end of file +
Basic Unified Balance with Chain Abstraction
+ + +**Cross Chain Swap (XCS)** + +Balance unification works at two levels, depending upon whether single token type is combined from source chains or can multiple token types be combined from source chains. The capability is subject to whether the chain and tokens supports `permit/EIP-2612': + +* Unified Balance (Basic) +* Unified Balance with Cross-Chain Swap (XCS) + +{% include "./text-snippets/ca/xcs_feature.md" %} + + + + diff --git a/includes/text-snippets/ca/xcs_feature.md b/includes/text-snippets/ca/xcs_feature.md new file mode 100644 index 00000000..020b18cc --- /dev/null +++ b/includes/text-snippets/ca/xcs_feature.md @@ -0,0 +1,52 @@ +The Arcana chain abstraction protocol has evolved to a cross-chain swap +enabled unified balance. + +**Basic Unified Balance** + +- Users could combine the same token type (for example, USDT) held across + multiple source chains into a single, unified balance. +- This allowed spending that token on any destination chain. +- **Limitation:** Users could only use the unified balance of a single + token type. If they lacked enough of that token on all the source + chains combined, or had no liquidity on the destination chain, they + could not complete the transaction. + +**Unified Balance with Cross-Chain Swap (XCS)** + +- The new improved unified balance approach allows cross-chain swaps. +- Users can now spend any supported token (for example, USDT, USDC) from + any supported source chain to pay on any destination chain. +- The protocol automatically combines multiple token types and + sources to fulfill the transaction, even if the user lacks + sufficient balance in a single token or on the destination chain. +- This significantly increases the available liquidity and flexibility, + enabling larger transactions and covers gas fee. +- This advanced feature requires chains and tokens to support `permit/EIP-2612`. +- The chain abstraction protocol falls back to the basic unified balance if the chains + and tokens do not support `permit/EIP-2612`. + +!!! an-example "Example" + + Consider a wallet balance: + + - *Optimism:* 0.1 ETH, 0 USDT, 0 USDC + - *Arbitrum:* 0 ETH, 12 USDT, 0 USDC + - *Base:* 0 ETH, 10 USDT, 0 USDC + - *Scroll:* 0 ETH, 0 USDT, 0 USDC + + With no unified balance or chain abstraction, user cannot spend any USDT on Scroll unless + they use a bridge to convert tokens. + + With basic unified balance and chain abstracted transaction, user can spend *18 USDT on Scroll*. + + XCS feature lets user spend **18 USDC on Scroll** which is not possible with basic unified balance. + + | Intent | No Unified Balance / CA | Unified Balance | Unified Balance + XCS | + |:---|:---|:---|:--- | + | Spend 18 **USDT** on Scroll | ❌ | ✅ | ✅ | + | Spend 18 **USDC** on Scroll | ❌ | ❌ | ✅ | + +
+ ![Intent Explorer]({{config.extra.arcana.img_dir}}/an_ca_xcs_feature.{{config.extra.arcana.img_png}}){ .an-screenshots } +
Unified Balance with Cross-Chain Swap
+
\ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index ec073476..9e12a5f2 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -560,6 +560,7 @@ nav: - Concepts: - Chain Abstraction: concepts/ca/chain-abstraction.md - Unified Balance: concepts/ca/unified-balance.md + - Cross-Chain Swap (XCS): concepts/ca/unified-xcs-balance.md - Allowances: concepts/ca/allowances.md - Intent: concepts/ca/intent.md - Intent Explorer: concepts/ca/intent-explorer.md