diff --git a/docs.json b/docs.json index 392d16b0..ad78a63c 100644 --- a/docs.json +++ b/docs.json @@ -2443,8 +2443,9 @@ "group": "Cross-Chain", "pages": [ "evm/integrations/cross-chain/index", + "evm/integrations/cross-chain/chainlink-ccip", "evm/integrations/cross-chain/layerzero", - "evm/integrations/cross-chain/chainlink-ccip" + "evm/integrations/cross-chain/usdt0" ] }, { diff --git a/evm/integrations/cross-chain/index.mdx b/evm/integrations/cross-chain/index.mdx index 83cc29d0..e04dc649 100644 --- a/evm/integrations/cross-chain/index.mdx +++ b/evm/integrations/cross-chain/index.mdx @@ -1,54 +1,57 @@ --- title: Interoperability and Bridging +description: "Explore Hedera's interoperability and bridging options: cross-chain messaging protocols like Chainlink CCIP and LayerZero, and ready-to-use bridged assets like USDT0." +mode: "wide" --- -Interoperability and bridging on Hedera enable seamless communication and asset transfers between Hedera and other blockchain networks. This will allow developers to create dApps across multiple blockchain platforms, furthering the functionality and versatility of applications. Projects like **LayerZero**, **Chainlink**, and **Hashport** are among the leading providers of these integrations. Learn more about these integrations below. +Interoperability and bridging let Hedera applications communicate and move assets across other networks so a dApp is not confined to a single chain. These integrations fall into two broad groups: + +- **Cross-chain messaging protocols** that carry arbitrary data and token transfers between chains, such as [Chainlink CCIP](/evm/integrations/cross-chain/chainlink-ccip) and [LayerZero](/evm/integrations/cross-chain/layerzero). +- **Ready-to-use bridged assets** that already span multiple chains, such as [USDT0](/evm/integrations/cross-chain/usdt0), the omnichain deployment of Tether's USDT. {" "} - - 🖥️ GETTING STARTED - -
- - 🧱 DOCUMENTATION - + Programmable cross-chain messaging and token transfers with built-in risk controls. {" "} - - 🖥️ GETTING STARTED - -
- 🧱 DOCUMENTATION + Omnichain messaging and token bridging via the OApp and OFT standards. {" "} - 🖥️ GETTING STARTED -
- 🧱 DOCUMENTATION + Omnichain USDT on Hedera, built on LayerZero's OFT standard. + +## Choosing an integration + +Match the integration to what you are trying to do, not the other way around. + +| Integration | Best for | You deploy a contract? | Under the hood | +| --- | --- | --- | --- | +| [Chainlink CCIP](/evm/integrations/cross-chain/chainlink-ccip) | Programmable cross-chain messaging and token transfers with risk controls | Yes, integrate the CCIP router and receiver | CCIP messaging plus supported token transfers | +| [LayerZero](/evm/integrations/cross-chain/layerzero) | Sending arbitrary messages or bridging your own token across chains | Yes, an OApp/OFT contract (or HTS Connector for HTS tokens) | OFT, ONFT, OFT Adapter, HTS Connector | +| [USDT0](/evm/integrations/cross-chain/usdt0) | Using a dollar stablecoin that already exists on Hedera and other chains | No, the token is already deployed | HTS token; LayerZero OFT | diff --git a/evm/integrations/cross-chain/layerzero.mdx b/evm/integrations/cross-chain/layerzero.mdx index 1e2bae36..0c904e05 100644 --- a/evm/integrations/cross-chain/layerzero.mdx +++ b/evm/integrations/cross-chain/layerzero.mdx @@ -1,5 +1,6 @@ --- title: "LayerZero" +description: "Learn how LayerZero's omnichain messaging and Omnichain Fungible Token (OFT) standard integrate with Hedera to bridge HTS and ERC tokens across chains." --- diff --git a/evm/integrations/cross-chain/usdt0.mdx b/evm/integrations/cross-chain/usdt0.mdx new file mode 100644 index 00000000..16e538cd --- /dev/null +++ b/evm/integrations/cross-chain/usdt0.mdx @@ -0,0 +1,226 @@ +--- +title: "USDT0 Omnichain Stablecoin on Hedera" +sidebarTitle: "USDT0" +description: "Integrate USDT0, the omnichain deployment of Tether's USDT, on Hedera. Move native USDT liquidity across 20+ chains with LayerZero's OFT standard, no wrapped tokens or third-party bridges." +--- + +[USDT0](https://usdt0.to/) is the omnichain deployment of Tether's USDT, the largest and most widely used dollar stablecoin. It is now live on Hedera, giving applications access to deep, cross-chain dollar liquidity that moves between networks as a single unified token, without wrapped assets, synthetic representations, or third-party bridges. + +USDT0 is built on LayerZero's Omnichain Fungible Token (OFT) standard, so the same USDT0 balance can move between Hedera and other supported chains with 1:1 backing and no liquidity fragmentation. It is a production deployment of the same standard covered generically in [LayerZero on Hedera](/evm/integrations/cross-chain/layerzero). See that page for the OFT, OFT Adapter, and HTS Connector building blocks. This page covers the USDT0 deployment specifically and how to use it. + + +For the background and Hedera's perspective on why this matters, read the announcement: [**Hedera integrates USDT0 for crosschain stablecoin liquidity**](https://hedera.com/blog/hedera-integrates-usdt0-for-crosschain-stablecoin-liquidity/). + + +## What USDT0 is (and what it is not) + + + + - **Native USDT liquidity** on Hedera, backed 1:1 by Tether's USDT + - A **single omnichain token**, the same asset across every supported chain + - Built on **LayerZero's OFT standard** for secure cross-chain messaging + - On Hedera, a standard **HTS fungible token** with an EVM-compatible interface + + + - **Not a wrapped or synthetic token** with its own separate liquidity pool + - **Not a third-party bridge** that issues a chain-specific IOU + - **Not a new stablecoin** with a separate peg or reserve from USDT + - **Not custodied by Hedera** or the LayerZero messaging layer + + + +## How it works + +USDT0 uses a lock-and-mint model anchored on Ethereum and an omnichain messaging layer to keep one unified supply across chains. + + + +The canonical USDT supply is held by an OFT Adapter contract on Ethereum mainnet. Locking USDT there authorizes an equivalent mint elsewhere. + + +An equivalent amount of USDT0 mints on the destination chain (such as Hedera) with strict 1:1 backing. + + +A cross-chain transfer burns USDT0 on the source chain and mints it on the destination chain. LayerZero's decentralized verifier network carries and validates the message, so no separate bridge liquidity pool is involved. + + +Burning USDT0 and routing back to Ethereum unlocks the original USDT from the adapter, keeping total supply constant. + + + +## USDT0 on Hedera + +On Hedera, USDT0 is a native **Hedera Token Service (HTS)** fungible token that is also reachable through its EVM address, so you can work with it from both native SDKs and EVM tooling such as ethers.js, Hardhat, or Foundry. + +| Detail | Value | +| --- | --- | +| Token name | USDT0 | +| Decimals | 6 | +| Hedera token ID | `0.0.10282787` | +| Token EVM address | `0x00000000000000000000000000000000009Ce723` | +| OFT contract (cross-chain send/receive) | `0xe3119e23fC2371d1E6b01775ba312035425A53d6` | +| LayerZero endpoint ID (EID) for Hedera | `30316` | +| Hedera EVM chain ID | `295` (mainnet) | + + +Contract addresses and endpoint IDs are reproduced here for convenience and were accurate at the time of writing. Always confirm against the canonical [USDT0 deployments page](https://docs.usdt0.to/technical-documentation/deployments) before sending value, and treat the official USDT0 documentation as the source of truth. + + + +Because USDT0 is an HTS token, a receiving Hedera account must be **associated** with the token before it can hold a balance. Accounts with automatic association slots available, or that already hold the token, do not need an explicit association. See [Token Association](/native/tokens/associate-tokens-to-an-account) for details. + + + +The underlying token is an **HTS token reached through Hedera's [EVM facade](/support/glossary#facade-contract)**, not a plain ERC-20. The OFT contract reports `approvalRequired() == true`, so you must `approve` the OFT to spend USDT0 before calling `send`; that approval routes through the HTS allowance facade. The OFT is deployed behind an **upgradeable proxy**, so confirm current behavior against the [USDT0 Developer Guide](https://docs.usdt0.to/technical-documentation/developer/) before integrating. + + +## Sending USDT0 across chains + +Cross-chain transfers go through the OFT contract, not a plain ERC-20 `transfer`. The flow is the same as any LayerZero OFT: quote the messaging fee, approve the amount if needed, then call `send`. You pay the LayerZero messaging fee in the source chain's native gas token (HBAR when sending from Hedera). + + +The code below **illustrates the standard LayerZero OFT pattern** so you can see the shape of the flow. It is not a Hedera-tested recipe. Treat the [**USDT0 Developer Guide**](https://docs.usdt0.to/technical-documentation/developer/) as the source of truth for working integration code — it ships maintained TypeScript/ethers.js examples — and verify the Hedera-specific behavior noted below before moving real value. + +In particular, mind the **tinybar/weibar unit difference**: `quoteSend` returns the fee in tinybars (8 decimals), but the JSON-RPC relay expects `msg.value` in weibars (18 decimals), so the fee must be converted before it is attached to `send`. See [Developer Considerations on the LayerZero page](/evm/integrations/cross-chain/layerzero#developer-considerations-to-note-evm-differences) for more on this. + + +The `send` function takes a `SendParam` struct and a `MessagingFee`: + +```solidity SendParam +struct SendParam { + uint32 dstEid; // destination chain LayerZero endpoint ID + bytes32 to; // recipient address, left-padded to bytes32 + uint256 amountLD; // amount to send, in local decimals (6 for USDT0) + uint256 minAmountLD; // minimum received after fees/slippage + bytes extraOptions; // execution options (e.g. gas for the destination) + bytes composeMsg; // optional composed message payload + bytes oftCmd; // OFT command bytes (empty for a standard send) +} + +struct MessagingFee { + uint256 nativeFee; // fee paid in native gas (HBAR on Hedera) + uint256 lzTokenFee; // optional fee paid in the LayerZero token +} +``` + +### Example: send USDT0 from Hedera with ethers.js + +```javascript send-usdt0.js +import { ethers } from "ethers"; + +// Minimal ABI for the OFT send flow. +const OFT_ABI = [ + "function quoteSend((uint32 dstEid, bytes32 to, uint256 amountLD, uint256 minAmountLD, bytes extraOptions, bytes composeMsg, bytes oftCmd) sendParam, bool payInLzToken) view returns ((uint256 nativeFee, uint256 lzTokenFee) fee)", + "function send((uint32 dstEid, bytes32 to, uint256 amountLD, uint256 minAmountLD, bytes extraOptions, bytes composeMsg, bytes oftCmd) sendParam, (uint256 nativeFee, uint256 lzTokenFee) fee, address refundAddress) payable returns ((bytes32 guid, uint64 nonce, (uint256 nativeFee, uint256 lzTokenFee) fee) msgReceipt, (uint256 amountSentLD, uint256 amountReceivedLD) oftReceipt)", + "function token() view returns (address)", +]; + +const ERC20_ABI = [ + "function approve(address spender, uint256 amount) returns (bool)", + "function allowance(address owner, address spender) view returns (uint256)", +]; + +// USDT0 OFT contract on Hedera mainnet. +const HEDERA_USDT0_OFT = "0xe3119e23fC2371d1E6b01775ba312035425A53d6"; + +// Left-pad a 20-byte EVM address to a 32-byte value. +function addressToBytes32(address) { + return ethers.zeroPadValue(address, 32); +} + +async function sendUsdt0({ provider, signer, dstEid, recipient, amount }) { + const oft = new ethers.Contract(HEDERA_USDT0_OFT, OFT_ABI, signer); + + const sendParam = { + dstEid, // e.g. 30110 for Arbitrum One + to: addressToBytes32(recipient), // recipient on the destination chain + amountLD: amount, // 6-decimal amount, e.g. 100 USDT0 = 100_000000n + minAmountLD: amount, // adjust to allow for slippage if needed + extraOptions: "0x", // default execution options + composeMsg: "0x", + oftCmd: "0x", + }; + + // 1. Quote the LayerZero messaging fee (paid in HBAR when sending from Hedera). + const fee = await oft.quoteSend(sendParam, false); + + // 2. Approve the OFT to pull the underlying token, if it is not already approved. + const tokenAddress = await oft.token(); + const token = new ethers.Contract(tokenAddress, ERC20_ABI, signer); + const owner = await signer.getAddress(); + const allowance = await token.allowance(owner, HEDERA_USDT0_OFT); + if (allowance < amount) { + await (await token.approve(HEDERA_USDT0_OFT, amount)).wait(); + } + + // 3. Send, attaching the native fee as msg.value. + // Hedera gotcha: quoteSend returns nativeFee in tinybars (8 decimals), but the + // JSON-RPC relay expects msg.value in weibars (18 decimals). Convert before sending. + const nativeFeeWeibars = fee.nativeFee * 10n ** 10n; + const tx = await oft.send(sendParam, fee, owner, { value: nativeFeeWeibars }); + return tx.wait(); +} +``` + + +`amountLD` and `minAmountLD` are expressed in USDT0's 6 decimals, so 100 USDT0 is `100_000000`. USDT0's OFT uses 6 shared decimals, matching its 6 local decimals, so there is no dust removal or rounding on transfer; the full amount you send is delivered. The LayerZero messaging fee is paid separately in HBAR (the `nativeFee`), not deducted from the transferred USDT0. + + +### Common destination endpoint IDs + +Use the destination chain's LayerZero endpoint ID (EID) as `dstEid`. A few common values: + +| Destination chain | Chain ID | LayerZero EID | +| --- | --- | --- | +| Ethereum | 1 | 30101 | +| Arbitrum One | 42161 | 30110 | +| Optimism | 10 | 30111 | +| Polygon PoS | 137 | 30109 | +| Hedera | 295 | 30316 | + +The full, authoritative list lives on the [USDT0 deployments page](https://docs.usdt0.to/technical-documentation/deployments) and the [LayerZero deployments reference](https://docs.layerzero.network/v2/deployments/deployed-contracts). + +## Using USDT0 as a regular token on Hedera + +Once USDT0 is on a Hedera account, it behaves like any other HTS fungible token for in-network use. You can transfer it between Hedera accounts, hold it in smart contracts, and use it in DeFi protocols using either the native SDKs or the EVM interface: + +- **Native SDKs:** use [`TransferTransaction`](/native/transactions/transfer-cryptocurrency) with the token ID `0.0.10282787`, and [associate the token](/native/tokens/associate-tokens-to-an-account) first if needed. +- **EVM tooling:** treat the token EVM address `0x00000000000000000000000000000000009Ce723` as a standard 6-decimal ERC-20. + +Reserve the OFT `send` flow for moving USDT0 **across chains**; a same-chain Hedera transfer is just a normal HTS or ERC-20 transfer. + +## Requirements and limitations + + +USDT0 is a third-party omnichain token. Hedera does not custody it or operate the cross-chain messaging layer. Review the official USDT0 and LayerZero documentation before moving real value. + + +- **The USDT0 token is mainnet-only:** USDT0 is deployed on Hedera **mainnet**; there is no Hedera testnet USDT0 token to test transfers against. LayerZero's messaging layer itself does have a [Hedera testnet endpoint](https://docs.layerzero.network/v2/deployments/chains/hedera-testnet) (EID 40285), so you can exercise OFT wiring on testnet with your own token. Validate the USDT0 path with small amounts on mainnet. +- **HBAR for fees:** Sending USDT0 from Hedera requires HBAR to cover both the Hedera transaction fee and the LayerZero messaging fee (the `nativeFee` you attach as `msg.value`). +- **Token association:** A receiving Hedera account must be associated with USDT0 (or have an open auto-association slot) before it can hold a balance. +- **6 decimals:** USDT0 uses 6 decimals on every chain, and its OFT uses 6 shared decimals, so cross-chain transfers move the exact amount with no dust rounding. +- **Destination gas:** Cross-chain delivery may require execution options (`extraOptions`) that allocate enough gas on the destination chain. Use `quoteSend` to price the transfer with the options you intend to use. +- **Confirm addresses:** Always verify contract addresses and endpoint IDs against the canonical USDT0 deployments page before integrating. + +## Resources + + + + Official USDT0 technical documentation, architecture, and developer guide. + + + Maintained TypeScript/ethers.js integration examples — the source of truth for working code. + + + Canonical contract addresses and endpoint IDs for every supported chain. + + + Hedera's announcement covering the what and why. + + + The OFT, OFT Adapter, and HTS Connector building blocks USDT0 is built on. + + + How the Omnichain Fungible Token standard works under the hood. + + diff --git a/images/open-source-solutions/interoperability-and-bridging/usdt0-card-logo.png b/images/open-source-solutions/interoperability-and-bridging/usdt0-card-logo.png new file mode 100644 index 00000000..ecd7fa24 Binary files /dev/null and b/images/open-source-solutions/interoperability-and-bridging/usdt0-card-logo.png differ diff --git a/support/glossary.mdx b/support/glossary.mdx index 828f1419..946296ef 100644 --- a/support/glossary.mdx +++ b/support/glossary.mdx @@ -466,9 +466,9 @@ An account controlled by [private keys](#private-key) that can send transactions --- -A facade contract on Hedera acts as a built-in adapter, allowing Hedera Token Service (HTS) tokens to function seamlessly as standard ERC-20 or ERC-721 tokens within EVM-compatible (EVM) environments. This integration enables developers to interact with HTS tokens using familiar Ethereum interfaces, such as `transfer()`, `approve()`, and `transferFrom()`, without requiring modifications to existing EVM wallets or decentralized applications (dApps). +A facade contract on Hedera is a built-in proxy that lets a Hedera Token Service (HTS) token be called as if it were a standard ERC-20 or ERC-721 contract from EVM-compatible (EVM) environments. Calls to familiar Ethereum interfaces such as `transfer()`, `approve()`, `allowance()`, and `transferFrom()` are redirected to the HTS system contract and executed by the native token service ([HIP-218](https://hips.hedera.com/hip/hip-218), [HIP-376](https://hips.hedera.com/hip/hip-376)), so most EVM wallets and decentralized applications (dApps) can work with HTS tokens without code changes. -Under the hood, when an EVM-compatible tool interacts with an HTS token's facade contract, the call is delegated to Hedera's native token service. This design ensures that HTS tokens can be managed and transacted using standard EVM tooling, providing a seamless developer experience. ​ +HTS-specific behavior still applies: an account must be **associated** with a token before it can hold a balance. The facade also exposes the HTS-native `associate()`, `dissociate()`, and `isAssociated()` functions through the IHRC interface ([HIP-719](https://hips.hedera.com/hip/hip-719)). ### Fair Order