网关 v1 提供者
Circle 的网关 v1 统一平衡套件提供者
即时跨链的USDC转移,跨链统一平衡管理.
目录
概览
Gateway v1 提供商是 Circle 的 Gateway 协议的强型执行,它能够 瞬间跨链USDC转让 对各支持区块链网络实行统一平衡管理.
虽然主要设计为电力 统一余额套件,该提供者也可以使用 直接在应用程序中 需要精细控制 Gateway 操作 或想要整合 Gateway 没有完整的 Stablecoin Kits 框架.
为什么是Gateway v1 提供者?
- * 即时跨链移动: 在一个流中从多个源链和目的地取出薄荷
- 统一平衡模式: 存款一次,花在任何地方——不等待连锁店之间的终结
- QQ Circle 的官方协议: 用于安全和可靠性的用户圈网关基础设施
- * 类型安全操作: 建有 TypeScript 严格模式并全面验证
- * 直接融合: 使用独立或自定义的管弦逻辑
安装
npm install @circle-fin/provider-gateway-v1
# or
yarn add @circle-fin/provider-gateway-v1
说明: 默认情况下包含此提供者 统一余额套件。如果需要进行自定义的Gateway集成,可以导入此提供者.
快速启动
备选案文1:统一平衡套件(建议)
import {
createUnifiedBalanceKitContext,
deposit,
spend,
getBalances,
} from '@circle-fin/unified-balance-kit'
// Provider included by default
const context = createUnifiedBalanceKitContext()
const result = await deposit(context, {
from: { adapter, chain: 'Ethereum' },
amount: '100',
})
const spendResult = await spend(context, {
amount: '50',
from: { adapter, allocations: { amount: '50', chain: 'Ethereum' } },
to: { adapter, chain: 'Base' },
})
const balances = await getBalances(context, { sources: { adapter } })
备选案文2:直接提供者的使用
import { createGatewayV1Provider } from '@circle-fin/provider-gateway-v1'
const provider = createGatewayV1Provider()
// Get supported chains
const chains = provider.getSupportedChains()
// Deposit USDC on a chain
await provider.deposit({
from: { adapter, chain: 'Ethereum' },
amount: '100',
token: 'USDC',
})
// Estimate spend fees
const estimate = await provider.estimateSpend({
from: {
adapter,
allocations: { amount: '100', chain: 'Ethereum' },
},
to: { adapter, chain: 'Base' },
token: 'USDC',
})
// Execute spend (mint on destination)
const result = await provider.spend({
from: {
adapter,
allocations: { amount: '100', chain: 'Ethereum' },
},
to: { adapter, chain: 'Base' },
token: 'USDC',
})
// Query balances
const balances = await provider.getBalances({
token: 'USDC',
sources: { adapter, chains: ['Ethereum', 'Base'] },
})
特征
- ✅ 存款 - 将USDC存入任何支持链的Gateway账户
- ✅ 支出(薄荷) - 从一条或多条链子上拉出 目的地有薄荷
- ✅ 余额查询 - 合计和每链USDC余额
- ✅ 代表团 - 为网关账户增加/调离代表
- ✅ 基金移除 - 启动并全部撤出网关
- ✅ 多来源支出 - 在一次行动中从多个链中分配金额
- ✅ 类型安全 - 配有结构化 KitError 处理的完整类型脚本支持
支持的链条
提供者支持所有带有Gateway v1配置的链条. 打电话 getSupportedChains() 完整名单。 主网的例子包括: 以利亚, (中文(简体) ), 坐标, (中文(简体) ), 基础, (中文(简体) ), 索拉纳; 测试网实例包括 伊特鲁姆·塞波利亚, (中文(简体) ), 塞波利亚基地, (中文(简体) ), 索拉纳·德夫内。 。 。 .
import { createGatewayV1Provider } from '@circle-fin/provider-gateway-v1'
const provider = createGatewayV1Provider()
const chains = provider.getSupportedChains()
console.log(chains.map((c) => c.name))
用法实例
基本业务
const provider = createGatewayV1Provider()
// Deposit
await provider.deposit({
from: { adapter, chain: 'Ethereum' },
amount: '100',
token: 'USDC',
})
// Spend (single source)
const result = await provider.spend({
from: { adapter, allocations: { amount: '50', chain: 'Ethereum' } },
to: { adapter, chain: 'Base' },
token: 'USDC',
})
console.log(result.txHash, result.explorerUrl)
// Spend (multi-source)
const multiResult = await provider.spend({
from: {
adapter,
allocations: [
{ amount: '30', chain: 'Ethereum' },
{ amount: '20', chain: 'Base' },
],
},
to: { adapter, chain: 'Avalanche' },
token: 'USDC',
})
余额查询
const provider = createGatewayV1Provider()
// By adapter
const balances = await provider.getBalances({
token: 'USDC',
sources: { adapter, chains: ['Ethereum', 'Base'] },
})
// By account address (read-only)
const balancesByAddress = await provider.getBalances({
token: 'USDC',
sources: { address: '0x...', chains: ['Ethereum', 'Base'] },
})
// Include pending deposits
const withPending = await provider.getBalances({
token: 'USDC',
sources: { adapter },
includePending: true,
})
处理错误
提供者抛出结构化 KitError 验证和执行失败的实例 :
import { createGatewayV1Provider } from '@circle-fin/provider-gateway-v1'
import { isKitError } from '@circle-fin/unified-balance-kit'
const provider = createGatewayV1Provider()
try {
const result = await provider.spend(params)
console.log('Success:', result.txHash)
} catch (error) {
if (isKitError(error)) {
console.error(`Error ${error.code}: ${error.name}`, error.message)
if (error.recoverability === 'RESUMABLE' && error.cause?.trace) {
const { attestation, signature, missingTokenAccounts } = error.cause
.trace as {
attestation: string
signature: string
missingTokenAccounts?: { tokenAccount: string; mint: string }[]
}
if (missingTokenAccounts?.length) {
// Solana only: create the listed token accounts first, then retry
// with the same attestation. Retrying now fails the same way.
throw error
}
// Mint failed after transfer—retry with config.retry
await provider.spend({
...params,
config: { retry: { attestation, signature } },
})
}
}
throw error
}
支出过程
Gateway v1 提供者处理全部花 (mint) 流量 :
- 估计数 - 从 Gateway API 获取费用估计
- 签名 - 为每个源链构建并签署燃烧意图
- 获取验证 - 提交经签名的意向,提交API网关,接受证明
- 薄荷 - 使用证明书执行目的地链上的薄荷交易
当薄荷步骤在获取证明后失败( 资金锁定), 提供者会扔出一个 KitError 与 recoverability: 'RESUMABLE' 财务报告和审定财务报表 attestation编号 :signature 内 cause.trace启用 config.retry 重新尝试薄荷而不重运行取回.
在索拉纳岛上,薄荷不会创建收款人代币账户. 下面的两个错误都列出缺少的账户 cause.trace.missingTokenAccounts如果缺失的账户属于圆形收费接受者,则联系圆形支持.
- 转移前 (非前导者花费和
estimateSpend:提供者在要求证明之前先检查收信人代号账户. 缺少的账户丢出VALIDATION_FAILEDKitError这是FATAL。未提交;创建账户,然后调用spend再来一次. - 薄荷时间 (例如关于
config.retry: 缺失的账户丢出VALIDATION_FAILEDKitError这是RESUMABLE创建账户,然后重试config.retry。在它们存在之前重试失败,错误相同.
与统一平衡套件合并
此提供者是专门为 统一余额套件数字 :
import { UnifiedBalanceKit } from '@circle-fin/unified-balance-kit'
import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
const kit = new UnifiedBalanceKit()
const adapter = createViemAdapterFromPrivateKey({
privateKey: process.env.PRIVATE_KEY as `0x${string}`,
})
// Monitor gateway events
kit.on('*', (event) => console.log('Event:', event))
kit.on('gateway.deposit.succeeded', (payload) =>
console.log('Deposit:', payload.data),
)
kit.on('gateway.spend.succeeded', (payload) =>
console.log('Spend succeeded:', payload.data.txHash),
)
// Execute operations
await kit.deposit({ from: { adapter, chain: 'Ethereum' }, amount: '100' })
const result = await kit.spend({
amount: '50',
from: { adapter, allocations: { amount: '50', chain: 'Ethereum' } },
to: { adapter, chain: 'Base' },
})
发展
这个包是"稳定币"(Stablecoin Kits monorepo)的一部分.
# Build
nx build @circle-fin/provider-gateway-v1
# Test
nx test @circle-fin/provider-gateway-v1
许可证
这个项目根据Apache 2.0许可证获得许可. 联系人 支助 详细情况.