> For the complete documentation index, see [llms.txt](https://docs.stacks.pet/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stacks.pet/stackspet/usdcx.md).

# USDCx

## 三、USDCx 跨链桥

### 3.1 跨链桥介绍

Stacks.PET 跨链桥用于在多个 EVM 网络与 Stacks 之间转移稳定币。

#### 跨入 Stacks

支持：

```
EVM USDC → USDCx
EVM USDT → USDC → USDCx
```

基本路径：

```
用户钱包
→ Stacks.PET 网络合约
→ Circle CCTP
→ Ethereum Settlement
→ Circle xReserve
→ Stacks USDCx
```

#### 跨出 Stacks

```
Stacks USDCx
→ Stacks.PET Clarity 合约
→ xReserve 销毁及结算
→ Ethereum 原生 USDC
→ 用户连接的 EVM 钱包
```

### 3.2 支持网络

| 网络        | USDC 跨入     | USDT 跨入 | Circle Domain |
| --------- | ----------- | ------- | ------------- |
| Ethereum  | 支持          | 支持      | 0             |
| Avalanche | 支持          | 支持      | 1             |
| Optimism  | 支持          | 不支持     | 2             |
| Arbitrum  | 支持          | 支持      | 3             |
| Base      | 支持          | 支持      | 6             |
| Polygon   | 支持          | 支持      | 7             |
| HyperEVM  | 支持          | 不支持     | 19            |
| Stacks    | USDCx 接收及跨出 | —       | xReserve 目标链  |

### 3.3 生产环境配置的合约地址

以下是当前项目环境中配置的地址。发布 GitBook 前，建议逐个在对应区块浏览器确认：

* 网络正确
* 地址存在合约字节码
* 构造参数正确
* 合约类型与文档一致
* 部署交易已确认

#### Ethereum

| 合约                 | 地址                                           |
| ------------------ | -------------------------------------------- |
| Settlement Factory | `0xe35f2fe9d02338741f0241e3d7dc3c87d9a125ac` |
| USDC Deposit       | `0x74e4aa89a18a13baa76b1984bd7a2a9f95b15de5` |
| USDT → USDCx       | `0x5afc4ede89b54fb583f4e16f14c2d3a4064c138a` |

#### Base

| 合约           | 地址                                           |
| ------------ | -------------------------------------------- |
| USDC → USDCx | `0x47eda1818a08f4e0bd063917e43f02eae40ea3c6` |
| USDT → USDCx | `0xfc4f1162ef02ef41df467a379d1cd539a1e6bcb6` |

#### Arbitrum

| 合约           | 地址                                           |
| ------------ | -------------------------------------------- |
| USDC → USDCx | `0xe35f2fe9d02338741f0241e3d7dc3c87d9a125ac` |
| USDT → USDCx | `0xdeef1141e9ef7bd0b2e04fc52692327ac8f72977` |

#### Optimism

| 合约           | 地址                                           |
| ------------ | -------------------------------------------- |
| USDC → USDCx | `0xe35f2fe9d02338741f0241e3d7dc3c87d9a125ac` |
| USDT → USDCx | 不支持                                          |

#### Polygon

| 合约           | 地址                                           |
| ------------ | -------------------------------------------- |
| USDC → USDCx | `0xb296bc927fa23675d6fd0231fb5ea08ca7e60856` |
| USDT → USDCx | `0xe35f2fe9d02338741f0241e3d7dc3c87d9a125ac` |

#### Avalanche

| 合约           | 地址                                           |
| ------------ | -------------------------------------------- |
| USDC → USDCx | `0xe35f2fe9d02338741f0241e3d7dc3c87d9a125ac` |
| USDT → USDCx | `0xb296bc927fa23675d6fd0231fb5ea08ca7e60856` |

#### HyperEVM

| 合约           | 地址                                           |
| ------------ | -------------------------------------------- |
| USDC → USDCx | `0xe35f2fe9d02338741f0241e3d7dc3c87d9a125ac` |
| USDT → USDCx | 不支持                                          |

#### Stacks

| 合约         | 地址                                                                  |
| ---------- | ------------------------------------------------------------------- |
| USDCx 跨出合约 | `SP2S3W6YFZS3YBZYA9GXT9W4R4H6BC8FR22DEAZC0.stacks-pet-usdcx-out-v1` |

> 多个网络出现相同的 `0xe35f...` 或 `0xb296...` 地址在 CREATE2 或相同部署账户/Nonce 场景下并非绝对不可能，但在正式发布文档前必须逐链核对字节码，不能只根据 `.env.local` 判断部署有效。

### 3.4 Circle 官方基础设施

| 基础设施                         | 地址                                           |
| ---------------------------- | -------------------------------------------- |
| Ethereum USDC                | `0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48` |
| Circle MessageTransmitter V2 | `0x81D40F21F12A8F0E3252Bccb954D722d4c464B64` |
| Circle TokenMessenger V2     | `0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d` |
| Circle xReserve              | `0x8888888199b2Df864bf678259607d6D5EBb4e3Ce` |

### 3.5 合约说明

#### `StacksPetMultichainUSDC`

用于 L2 原生 USDC 跨入 Stacks。

主要逻辑：

1. 用户授权 USDC。
2. 合约检查最低跨链金额。
3. 收取 0.5% Stacks.PET 手续费。
4. 剩余 USDC 通过 Circle CCTP 销毁。
5. 发出 `BridgeStarted` 事件。
6. Keeper 获取 Circle Attestation。
7. Ethereum Settlement Vault 接收并通过 xReserve 发往 Stacks。

关键参数：

```
最低金额：10 USDC
协议手续费：0.5%
```

关键事件：

```
BridgeStarted(
    address sender,
    bytes32 stacksRecipient,
    address ethereumVault,
    uint256 grossAmount,
    uint256 protocolFee,
    uint256 cctpAmount
)
```

#### `StacksPetUSDCDeposit`

用于 Ethereum 原生 USDC 直接进入 xReserve。

主要逻辑：

1. 用户授权 Ethereum USDC。
2. 合约收取 0.5% 手续费。
3. 净额提交给 xReserve。
4. xReserve 在 Stacks 上结算 USDCx。

关键事件：

```
USDCxDeposit(
    address sender,
    bytes32 stacksRecipient,
    uint256 grossAmount,
    uint256 fee,
    uint256 netAmount
)
```

#### `StacksPetSwapToUSDC`

用于 L2 USDT 跨入。

路径：

```
USDT
→ V3-compatible DEX Router
→ 原生 USDC
→ 扣除 0.5% 手续费
→ Circle CCTP
→ Ethereum
→ xReserve
→ USDCx
```

合约提供最低输出保护，避免兑换价格异常。

关键事件：

```
SwapBridgeStarted(
    address sender,
    bytes32 stacksRecipient,
    uint256 grossUsdt,
    uint256 grossUsdc,
    uint256 protocolFee,
    uint256 cctpAmount
)
```

#### `StacksPetEthereumSwapToUSDCx`

用于 Ethereum USDT 跨入 Stacks。

与 L2 版本不同，兑换后的 Ethereum USDC 可以直接交给 xReserve，不需要再进行 L2 → Ethereum 的 CCTP 转移。

路径：

```
Ethereum USDT
→ V3 Router
→ Ethereum USDC
→ 扣除 0.5%
→ xReserve
→ Stacks USDCx
```

#### `StacksPetUSDCVaultFactory`

为每个 Stacks 收款地址生成确定性 Ethereum Settlement Vault。

职责：

* 将 Stacks 地址映射为确定性 Vault
* 接收 CCTP 铸造的 Ethereum USDC
* 将资金转交 xReserve
* 防止 Keeper 任意修改收款地址

#### `stacks-pet-usdcx-out-v1`

Stacks 上的 Clarity 跨出合约。

主要逻辑：

1. 用户提交 USDCx。
2. 检查最低 10 USDCx。
3. 收取 0.5% 手续费。
4. 净额进入 xReserve 跨出流程。
5. 输出包含 Ethereum 收款地址的链上事件。
6. 索引器跟踪 Ethereum 最终到账。

关键入口：

```
withdraw-usdc
```

关键事件：

```
stacks-pet-usdcx-withdrawal
```

### 3.6 手续费说明

#### Stacks.PET 手续费

```
0.5%
```

计算方式：

```
协议手续费 = 输入金额 × 0.5%
净跨链金额 = 输入金额 − 协议手续费
```

#### Circle / xReserve 费用

Circle 或 xReserve 可能另外收取跨链、Forwarding 或 Withdrawal 费用。

这些费用：

* 不归 Stacks.PET 所有
* 可能根据路线变化
* 应在前端提交前读取或预估
* 最终金额以 Circle/xReserve 结算结果为准

#### USDT 兑换损耗

USDT 路径还可能产生：

* DEX 池费
* 价格影响
* 滑点
* Gas 费用

因此：

```
实际到账 = USDT 兑换所得 USDC
         − Stacks.PET 手续费
         − Circle/xReserve 费用
```

### 3.7 Keeper 与 Attestation

Keeper 的职责：

1. 监听各源网络合约事件。
2. 读取 CCTP Message。
3. 请求 Circle Attestation。
4. 在 Ethereum 调用 MessageTransmitter。
5. 将收到的 USDC 交给确定性 Vault。
6. Vault 通过 xReserve 发往 Stacks。
7. 更新数据库状态。

### 3.8 跨链状态

| 状态             | 含义                             |
| -------------- | ------------------------------ |
| 钱包已提交          | 用户已在钱包广播源链交易                   |
| 源链确认中          | 等待源链交易打包确认                     |
| 源链已确认          | 合约事件已被索引                       |
| 等待 Attestation | Circle 正在生成跨链证明                |
| CCTP 已接收       | Ethereum 已接收并铸造 USDC           |
| 已提交 xReserve   | 资金已交给 xReserve                 |
| 等待 Stacks 结算   | 等待 USDCx 在 Stacks 链释放          |
| Stacks 已到账     | 已检测到 Stacks 收款交易               |
| 跨出处理中          | USDCx 已在 Stacks 销毁，等待 Ethereum |
| Ethereum 已到账   | 原生 USDC 已到达 EVM 钱包             |
| 失败             | 源链交易失败或合约调用回滚                  |

预计耗时：

```
跨入 Stacks：约 15–20 分钟
跨出 Stacks：约 15–20 分钟
```

网络拥堵、Circle Attestation 和 xReserve 结算可能导致延迟。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.stacks.pet/stackspet/usdcx.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.