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..f50a6531 --- /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: .. +--- + +# Unified Cross-Chain Swap + +{% 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..a8ad17ee Binary files /dev/null and b/docs/img/an_ca_xcs_feature.webp differ diff --git a/docs/web3-stack/ca_stack.md b/docs/web3-stack/ca_stack.md index 7bb0176d..82ee2e10 100644 --- a/docs/web3-stack/ca_stack.md +++ b/docs/web3-stack/ca_stack.md @@ -11,6 +11,7 @@ arcana: The {{config.extra.arcana.ca_sdk_name}} supports [[concept-unified-balance|unified balance]] and [[concept-ca|chain-abstracted transactions]] for the chains and tokens^*^ listed below. To execute a chain-abstracted transaction, you need enough unified balance of the token type on the source chain. This balance must cover both the gas fee and the transaction amount on the destination chain. +>>>>>>> main ^*^ *Every chain may not support all tokens. The list of supported chains and tokens may differ for the Coral and the Folly testnet. The chains supported by the SDK and those supported in the standalone, CA wallet used in the demos may not always be the same.* @@ -18,163 +19,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 | ✅ | - -### 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..1ad3ea90 --- /dev/null +++ b/includes/text-snippets/ca/generated_chainlist.md @@ -0,0 +1,180 @@ +!!! an-note "Unified Balance (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 older 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 | ✅ | ❌ | + +### 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..eaef76a3 100644 --- a/includes/text-snippets/ca/unified_balance.md +++ b/includes/text-snippets/ca/unified_balance.md @@ -1,22 +1,32 @@ -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 across multiple chains and tokens. -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. +Chain abstraction lets users spend available liquidity on any destination chain. No bridges or pre-provisioned gas are needed. All cross-chain complexity is handled behind the scenes. Users approve 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 +**Unified Balance Levels** -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. +Balance unification works at two levels, depending on chain and token support: +- **Baseline Chain Cbstraction (CA):** Combines a single token type from source chains. Users spend the unified balance of that token on any destination chain. +- **Cross-Chain Swap (XCS):** Combines multiple token types from source chains. Users spend as any token on any destination chain. This advanced feature requires chains and tokens to support `permit/EIP-2612`. -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. +!!! an-example "Example" -The cross-chain swap enables users to: + | CA | XCS | + |:---|:---| + | User wants to spend **18 USDT** on *Scroll*.| User wants to spend **18 USDC** on *Scroll*.| + | The wallet balance is:| The wallet balance is:| + | | | + | *Optimism:* 0.1 ETH, 0 USDT, 0 USDC | *Optimism:* 0.1 ETH, 0 USDT, 0 USDC | + | *Arbitrum:* 0 ETH, 12 USDT, 0 USDC | *Arbitrum:* 0 ETH, 12 USDT, 0 USDC | + | *Base:* 0 ETH, 10 USDT, 0 USDC | *Base:* 0 ETH, 10 USDT, 0 USDC | + | *Scroll:* 0 ETH, 0 USDT, 0 USDC | *Scroll:* 0 ETH, 0 USDT, 0 USDC | + | | | + | CA allows user to use unified USDT balance on Arbitrum | XCS allows user to use unified USDT balance and + | and Base and spend 18 USDT on Scroll. | spend it as USDC 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. +Both types let users spend assets on any chain, even without prior liquidity on the destination chain. Cross-chain swap also allows combining multiple supported assets across chains, solving liquidity fragmentation.
With CA
Single chain liquidity vs. Unified Balance with Chain Abstraction
-
\ No newline at end of file + + diff --git a/includes/text-snippets/ca/xcs_feature.md b/includes/text-snippets/ca/xcs_feature.md new file mode 100644 index 00000000..1a703443 --- /dev/null +++ b/includes/text-snippets/ca/xcs_feature.md @@ -0,0 +1,57 @@ +The Arcana chain abstraction protocol has evolved to a cross-chain swap +enabled unified balance. + +**Unified Balance** + +- Users could combine the same token type (e.g., 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. + +??? an-example "Example" + + User wallet balance: + 0 USDT on Scroll, + 0.25 USDC and 0.5 USDT on Arbitrum + 0.75 USDT on Base + + To spend 0.8 USDT on Scroll is not possible considering balance + on Scroll. + + Unified balance (Arbitrum + Base) allows the chain + abstracted transaction, but only with USDT. + + User cannot make a larger transaction, say 1.0 USDT and also + utilize the 0.25 USDC available on Arbitrum. + +**Unified Balance + XCS** + +- The new improved unified balance approach allows cross-chain swaps. +- Users can now spend any supported token (e.g., 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. + +??? an-example "Example" + + User wallet balance: + 0 USDT on Scroll, + 0.25 USDC and 0.5 USDT on Arbitrum + 0.75 USDT on Base + + To spend 1.0 USDT on Scroll is not possible considering balance + on Scroll. + + Unified balance (Arbitrum + Base, USDT+USDC) allows the chain + abstracted transaction. + +
+ ![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/includes/text-snippets/ca_supported_tokens.md b/includes/text-snippets/ca_supported_tokens.md deleted file mode 100644 index 711596f6..00000000 --- a/includes/text-snippets/ca_supported_tokens.md +++ /dev/null @@ -1,9 +0,0 @@ -|Tokens|Status| -|:---|:---| -|ETH | ✅ | -|USDT | ✅ | -|USDC | ✅ | -|WETH^*^ | ✅ | -|Native/Gas Tokens | ✅ | - -^*^ *where applicable, on supported chains.* diff --git a/mkdocs.yml b/mkdocs.yml index 87e0c9e9..a666f3f5 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -551,6 +551,7 @@ nav: - Concepts: - Chain Abstraction: concepts/ca/chain-abstraction.md - Unified Balance: concepts/ca/unified-balance.md + - Unified Cross-Chain Swap Balance: concepts/ca/unified-xcs-balance.md - Allowances: concepts/ca/allowances.md - Intent: concepts/ca/intent.md - Intent Explorer: concepts/ca/intent-explorer.md