Auroran Bridge 合约接口

EVM 充提桥接合约 · 可升级（TransparentUpgradeableProxy）

用户交互入口为 Proxy 地址（非 implementation）。

1. 数据结构

DepositEntry

充值记录（仅成功落账）。

字段	类型	说明
`owner`	`address`	充值人地址
`recordedAtBlock`	`uint64`	`deposit()` 成功时的区块号
`amount`	`uint256`	代币数量（原生精度）
`recordedAtTs`	`uint64`	`deposit()` 成功时的区块时间戳（秒）

WithdrawEntry

提款记录（仅成功放款）。

字段	类型	说明
`recipient`	`address`	收款 EVM 地址
`zeptoRequestId`	`uint64`	Auroran 链提现请求 ID（去重键；合约字段名）
`amount`	`uint256`	代币数量（原生精度）
`settledAtBlock`	`uint64`	放款成功时的区块号
`settledAtTs`	`uint64`	放款成功时的区块时间戳（秒）

序号约定

名称	规则
`seq`（充值）	1-based，`deposits` 数组下标 + 1；0 表示不存在
`withdrawId`（提款）	1-based，`withdrawals` 数组下标 + 1；0 表示不存在
`zeptoRequestId`	Auroran 链 `request_id`，映射表 `withdrawRequestIdToId` 去重

2. 写入函数

2.1 deposit

用户充值代币到 Auroran 链。

function deposit(uint256 amount) external returns (uint64 seq);

参数	类型	说明
`amount`	`uint256`	充值数量（代币原生精度，须 > 0）

返回	说明
`seq`	分配的充值序号（1-based）

行为：

代币从 msg.sender 经 safeTransferFrom 转入 projectAddress。
成功后 push deposits 并发出 DepositRecorded。
调用方须先对 Bridge 地址 approve。
修饰符：nonReentrant、whenDepositsNotPaused。

2.2 settleWithdraw

结算一笔 Auroran 链提款，向收款人放款。

function settleWithdraw(
    uint64 zeptoRequestId,
    uint256 amount,
    address recipient
) external returns (uint64 withdrawId);

参数	类型	说明
`zeptoRequestId`	`uint64`	Auroran 链提现请求 ID（去重键）
`amount`	`uint256`	放款数量（须 > 0）
`recipient`	`address`	收款 EVM 地址（非零）

返回	说明
`withdrawId`	分配的自增提款 ID（1-based）

行为：

无权限限制；代币从 msg.sender 转入 recipient，调用方须先 approve。
zeptoRequestId 重复提交 revert ZeptoRequestIdAlreadyUsed。
修饰符：nonReentrant、whenWithdrawalsNotPaused。

2.3 管理函数

函数	权限	说明
`setProjectAddress(address)`	`onlyOwner`	设置充值收款地址
`setOperator(address)`	`onlyOwner`	设置操作员
`setBlockConfirmations(uint64)`	`onlyOwner`	设置充值区块确认数
`pauseDeposits()`	`owner` 或 `operator`	暂停充值
`unpauseDeposits()`	`onlyOwner`	恢复充值
`pauseWithdrawals()`	`onlyOwner`	暂停提款
`unpauseWithdrawals()`	`onlyOwner`	恢复提款
`transferOwnership(address)`	`onlyOwner`	转移所有权
`renounceOwnership()`	`onlyOwner`	放弃所有权

2.4 initialize

Proxy 部署时调用一次（非对接方日常使用）。

function initialize(
    address token_,
    address projectAddress_,
    address operator_,
    address owner_,
    string calldata chainTag_,
    uint256 chainId_,
    uint64 blockConfirmations_
) external;

参数	说明
`token_`	桥接 ERC20 地址
`projectAddress_`	充值收款地址
`operator_`	可暂停充值的操作员
`owner_`	合约 owner
`chainTag_`	外部链标识（小写，如 `"bsc"`）
`chainId_`	须等于 `block.chainid`
`blockConfirmations_`	充值事件确认区块数

3. 读取函数

3.1 元数据

函数	返回	说明
`token()`	`address`	桥接 ERC20 地址
`projectAddress()`	`address`	充值收款地址
`operator()`	`address`	操作员地址
`owner()`	`address`	合约 owner
`chainTag()`	`string`	外部链标识
`chainId()`	`uint256`	EVM chain ID
`blockConfirmations()`	`uint64`	充值确认区块数
`depositsPaused()`	`bool`	充值是否暂停
`withdrawalsPaused()`	`bool`	提款是否暂停

3.2 bridgeChainInfo

一次性返回桥接实例元数据（链下程序启动时调用）。

function bridgeChainInfo() external view returns (
    string memory tag,
    uint256 id,
    address tokenAddr,
    uint8 tokenDecimals,
    address upgradeAdmin,
    address operatorAddr,
    uint64 confirmations
);

返回字段	说明
`tag`	`chainTag`
`id`	`chainId`
`tokenAddr`	桥接代币地址
`tokenDecimals`	代币 `decimals()`
`upgradeAdmin`	ProxyAdmin owner（非 proxy 部署时为 `address(0)`）
`operatorAddr`	操作员地址
`confirmations`	`blockConfirmations`

3.3 账本查询

函数	说明
`depositCount()`	已成功充值笔数
`withdrawCount()`	已成功提款笔数
`getDeposit(uint64 seq)`	按 seq 查充值（1-based），不存在 revert
`getWithdraw(uint64 withdrawId)`	按 withdrawId 查提款（1-based），不存在 revert
`getDeposits(uint64 offset, uint64 limit)`	分页查充值（offset 0-based，limit > 0）
`getWithdrawals(uint64 offset, uint64 limit)`	分页查提款
`isZeptoRequestIdUsed(uint64 requestId)`	Auroran 链请求 ID 是否已结算
`deposits(uint256 index)`	公开映射，按 0-based 下标读充值
`withdrawals(uint256 index)`	公开映射，按 0-based 下标读提款
`withdrawRequestIdToId(uint64)`	`zeptoRequestId` → `withdrawId`

4. 状态变量

变量	类型	说明
`token`	`IERC20`	桥接代币
`projectAddress`	`address`	充值收款地址
`operator`	`address`	操作员
`deposits`	`DepositEntry[]`	充值账本
`withdrawals`	`WithdrawEntry[]`	提款账本
`withdrawRequestIdToId`	`mapping(uint64 => uint64)`	去重索引
`depositsPaused`	`bool`	充值暂停开关
`withdrawalsPaused`	`bool`	提款暂停开关
`chainTag`	`string`	外部链标识
`chainId`	`uint256`	EVM chain ID
`blockConfirmations`	`uint64`	充值确认区块数

5. 事件

DepositRecorded

用户充值成功。

event DepositRecorded(
    uint64 indexed seq,
    address indexed owner,
    uint256 amount,
    uint64 blockNumber,
    uint64 timestamp
);

字段	索引	说明
`seq`	indexed	充值序号，对应 `external_ref.seq`
`owner`	indexed	充值人
`amount`	—	代币原生精度
`blockNumber`	—	落账区块号
`timestamp`	—	落账时间戳（秒）

WithdrawSettled

提款放款成功。

event WithdrawSettled(
    uint64 indexed withdrawId,
    uint64 indexed zeptoRequestId,
    address indexed recipient,
    uint256 amount,
    uint64 blockNumber,
    uint64 timestamp
);

字段	索引	说明
`withdrawId`	indexed	自增提款 ID
`zeptoRequestId`	indexed	Auroran 链 `request_id`
`recipient`	indexed	收款地址
`amount`	—	代币原生精度
`blockNumber`	—	放款区块号
`timestamp`	—	放款时间戳（秒）

管理事件

事件	参数	说明
`OwnershipTransferred`	`previousOwner`, `newOwner`	所有权变更
`ProjectAddressChanged`	`newAddress`	充值收款地址变更
`OperatorChanged`	`newOperator`	操作员变更
`BlockConfirmationsChanged`	`newBlockConfirmations`	确认区块数变更
`DepositsPaused`	—	充值已暂停
`DepositsUnpaused`	—	充值已恢复
`WithdrawalsPaused`	—	提款已暂停
`WithdrawalsUnpaused`	—	提款已恢复
`Initialized`	`version`	Proxy 初始化（OpenZeppelin）

6. 错误

错误	参数	场景
`ZeroAddress`	—	地址参数为零
`ZeroAmount`	—	金额为 0
`DepositsPausedError`	—	充值已暂停
`WithdrawalsPausedError`	—	提款已暂停
`DepositNotFound`	`seq`	充值序号不存在
`WithdrawNotFound`	`withdrawId`	提款 ID 不存在
`ZeptoRequestIdAlreadyUsed`	`requestId`	重复结算
`TransferAmountMismatch`	`balanceBefore`, `balanceAfter`, `expectedDelta`	转账金额不符（fee-on-transfer 代币等）
`NotOperator`	—	非 owner/operator 调用 `pauseDeposits`
`OwnableUnauthorizedAccount`	`account`	非 owner
`ReentrancyGuardReentrantCall`	—	重入
`EmptyChainTag`	—	初始化时 chainTag 为空
`ChainIdMismatch`	`expected`, `actual`	初始化 chainId 与链不符
`InvalidPagination`	—	`limit == 0`
`AlreadyInitialized`	—	重复初始化
`SafeERC20FailedOperation`	`token`	ERC20 操作失败

7. 设计约束

约束	说明
不托管资金	充值直达 `projectAddress`，提款由调用方出资
仅记录成功	转账失败整笔 revert，不写入账本
去重	充值靠 Auroran 链 `external_ref`；提款靠 `zeptoRequestId`
可升级	通过 TransparentUpgradeableProxy + ProxyAdmin
重入保护	`deposit` / `settleWithdraw` 使用 `nonReentrant`

1. 数据结构​

DepositEntry​

WithdrawEntry​

序号约定​

2. 写入函数​

2.1 deposit​

2.2 settleWithdraw​

2.3 管理函数​

2.4 initialize​

3. 读取函数​

3.1 元数据​

3.2 bridgeChainInfo​

3.3 账本查询​

4. 状态变量​

5. 事件​

DepositRecorded​

WithdrawSettled​

管理事件​

6. 错误​

7. 设计约束​

1. 数据结构

DepositEntry

WithdrawEntry

序号约定

2. 写入函数

2.1 deposit

2.2 settleWithdraw

2.3 管理函数

2.4 initialize

3. 读取函数

3.1 元数据

3.2 bridgeChainInfo

3.3 账本查询

4. 状态变量

5. 事件

DepositRecorded

WithdrawSettled

管理事件

6. 错误

7. 设计约束