跳到主要内容

资产归集

中心化类型的平台,例如交易所、加密银行、资产管理平台、借贷平台、支付平台、托管平台等,都面临如何高效、低成本归集用户充值的数字资产的课题。

通过本教程,您将了解以下内容:

  1. 归集和加油的具体含义
  2. 如何通过 Auto Sweep 和 Safeheron API 完成数字资产的归集

什么是归集

一般来说,交易所或者借贷类型的业务平台,会为每位用户分配一个独立的充值(存款)钱包。当多个用户存入数字资产到充值钱包,这些资产会分散在多个钱包中,不便于统一管理和使用,因此大多数的平台都会将这些资产统一归拢到一个钱包账户,资产归拢的过程我们就称为归集

什么是加油(补充 Gas)

当需要把 ERC20 、 TRC20 等基于智能合约的 Token 代币资产归集或者转移到其他钱包时,需要支付一定的原生资产作为 Gas,才能完成归集或转账。例如,用户存入 ERC20 代币到一个新创建的钱包,此时我们无法归集,因为用户的钱包地址上还没有 ETH 资产来支付 Gas。为了完成归集,需要向此用户的钱包转入一定量的 ETH ,用来支付在归集时需要的 Gas,这个就称为加油(补充 Gas)

如何归集资产

在 Safeheron 平台,可以通过两种方式自动化完成数字资产的归集:

两种方式对比如下:

Auto Sweep(推荐)利用 API 自助归集
API Co-Signer必须可选
研发投入几乎零成本需要自主研发类似 Auto Sweep 的应用,投入成本比较大
钱包范围仅支持通过 API 创建并且标记为 DEPOSIT 的资产钱包全部资产钱包
实现方式Auto Sweep 策略配置自动完成通过创建交易 API 完成
通过 API 查询归集加油交易记录支持支持
Webhook 通知支持支持
Web 控制台交易记录的平台交易类型明确显示为归集补充 Gas交易记录无特殊标记,平台交易类型显示为 普通

Auto Sweep

Auto Sweep 是面向机构客户的 Bot 应用,提供自动化归集资产的服务,点此查看 Auto Sweep 的详细介绍。

提示

使用 Auto Sweep 必须同时满足以下条件:

  1. 安装的手机 App 版本不低于 1.2.7
  2. 部署 API Co-Signer

部署 API Co-Signer

如果您已经部署了 API Co-Signer,则无需重复部署;如果您尚未部署,请点此查看 API Co-Signer 的介绍,并向 Safeheron Support 团队获取部署及如何使用的信息。

标记钱包

Auto Sweep 仅对通过 API 创建且同时带有 DEPOSIT 标记的钱包中的数字资产进行归集,您可以通过两种方式标记钱包:

  1. 使用创建钱包账户或者批量创建钱包账户 API 创建钱包时,把 accountTag 参数设置为 DEPOSIT
  2. 创建钱包之后,使用批量标记钱包账户 API 接口,更新钱包的标记为 DEPOSIT

接口参数示例如下:

{
// 说明:仅展示关键参数,实际请求接口时,需要对参数进行加密及签名,
// 具体请参考 API 文档中的 API 鉴权部分说明
"accountName": "example",
"hiddenOnUI": true,
"accountTag": "DEPOSIT"
}

配置 Auto Sweep 策略

Auto Sweep 策略支持您从多个方面进行灵活设置,例如:区块链网络、触发条件、归集频率、网络费用上限、Gas Station 等等,点击这里查看配置 Auto Sweep 策略的详细说明。

Auto Sweep 执行策略

当带有 DEPOSIT 标记的钱包有数字资产(仅 Safeheron 平台支持的 Token)转入,并且符合 Auto Sweep 策略要求时,Auto Sweep 应用将自动启动归集任务。如果您启用了 Gas Station,则当被归集的钱包 Gas 不足时,Auto Sweep 应用将自动为此钱包加油,即从 Gas Station 为该钱包补充 Gas。整个过程自动完成

需要注意的是,对一个钱包执行一次归集可能会同时产生归集和加油两条交易记录,也可能仅产生一条归集交易记录,这由是否经过 Gas Station 加油决定。

API Co-Signer 自动审批签名

与其他交易任务相同,Auto Sweep 发起归集或者加油交易后,API Co-Signer 将会请求您的交易审批业务系统对交易任务审核并授权,您的交易审批业务系统需要决定是否允许签名。为了与其他交易任务区分,凡是 Auto Sweep 发起的归集和加油交易,交易数据特征及示例如下:

  • transactionType 的值为 AUTO_SWEEP 为归集交易
  • transactionType 的值为 AUTO_FUEL 为加油交易
{
// 说明:仅展示部分数据
"sourceAccountKey": "account4b***34234",
"sourceAccountType": "VAULT_ACCOUNT",
"sourceAddress": "0xCa***4FBC5",
"destinationAccountKey": "account46***a2158",
"destinationAddress": "0xC1***34234",
"transactionType": "AUTO_SWEEP",
"transactionStatus": "SUBMITTED",
"txFee": "0.000106841386050000",
"feeCoinKey": "ETH(SEPOLIA)_ETHEREUM_SEPOLIA",
"customerRefId": "a1ef6672-***-ff30d392e723",
"customerExt1": "1",
"customerExt2": "2",
"txAmountToUsd": "19.9813552",
}
提示

需要注意的是,因为归集和加油交易是由 Auto Sweep 发起,所以在 API Co-Signer 审批时,您的业务系统中可能没有相关的交易记录,即使您已经通过交易查询接口或者 Webhook 来同步交易记录,也无法保证先于 API Co-Signer 审批同步到交易记录。

交易记录及 Webhook 通知

与其他交易任务相同,可通过以下四种方式查看获取 Auto Sweep 发起的归集和加油交易记录:

  • 通过 Web 控制台中的历史 -> 资产钱包交易记录页面查看归集和加油记录
  • 通过交易列表 API 获取归集和加油记录
  • 可在手机 App 中钱包的交易记录中查看某个钱包下的归集加油记录
  • 同时,如果您配置了 Webhook,归集和加油的交易记录也将通过 Webhook 通知到您配置的回调地址

为了与其他交易任务区分,归集和加油交易数据特征及示例如下:

  • transactionType 的值为 AUTO_SWEEP 为归集交易
  • transactionType 的值为 AUTO_FUEL 为加油交易
{
// 说明:仅展示部分数据
"sourceAccountKey": "account4b***34234",
"sourceAccountType": "VAULT_ACCOUNT",
"sourceAddress": "0xCa***4FBC5",
"destinationAccountKey": "account46***a2158",
"destinationAddress": "0xC1***34234",
"transactionType": "AUTO_SWEEP",
"transactionStatus": "SUBMITTED",
"txFee": "0.000106841386050000",
"feeCoinKey": "ETH(SEPOLIA)_ETHEREUM_SEPOLIA",
"customerRefId": "a1ef6672-***-ff30d392e723",
"customerExt1": "1",
"customerExt2": "2",
"txAmountToUsd": "19.9813552",
}

利用 API 自助归集

提示

如果您部署的有 API Co-Signer,推荐您使用 Auto Sweep 完成数字资产的归集

通过 API 来完成数字资产的归集,您需要做以下事情:

  1. 通过 API 创建交易接口 /v2/transactions/create 发起交易
  2. 通过手机 App 或者 API Co-Signer 进行审批签名

我们假设一个场景来举例说明:

您拥有一个交易所平台(简称平台),当新用户 Pillar 注册完成时,平台要创建一个新的钱包(也可以预先创建一批钱包,从中选取一个未使用的),分配给 Pillar 作为充值钱包使用。Pillar 向钱包中转入一笔 USDT ERC20 资产,平台需要把这笔资产归集到平台的热提钱包。为了完成归集,平台从热提钱包(您也可以设置专用的钱包用来加油)向 Pillar 的充值钱包转入一些 ETH 作为 Gas。假设数据如下:

数据项值举例
分配给 Pillar 充值钱包 accountKeyaccount2f0e3de53e474037a8fd8e9e672c34d0
平台热提钱包 accountKeyaccount6f85b6e5b800417ebe99209454efcb06
手续费币种标识 coinKeyETH
充值资产的币种标识 coinKeyUSDT_ERC20
充值金额10000 USDT

创建交易

归集和加油交易本质上是转移资产的一笔普通交易,可以通过创建交易接口来实现。其中,是否需要加油根据充值钱包中的 Gas 费是否充足决定,并不是每次归集都需要加油,即:

  • 充值钱包无 Gas 或 Gas 不足时,先加油再归集,共需创建两笔交易
  • 充值钱包 Gas 充足时可直接归集,仅需创建一笔交易

以下是创建加油交易和创建归集交易时请求接口的参数示例:

{
// 说明:仅展示关键参数,实际请求接口时,需要对参数进行加密及签名,
// 具体请参考 API 文档中的 API 鉴权部分说明
// 平台热提钱包的 accountKey
"sourceAccountKey":"account6f85b6e5b800417ebe99209454efcb06",
"sourceAccountType":"VAULT_ACCOUNT",
// 分配给 Pillar 充值钱包
"destinationAccountKey":"account2f0e3de53e474037a8fd8e9e672c34d0",
"destinationAccountType":"VAULT_ACCOUNT",

// 手续费币种标识 coinKey
"coinKey":"ETH",
// 推荐每次加油的金额可以用来支付3到5笔交易的手续费。
"txAmount":"some amount eth",
// 此示例采用交易费用等级,也可以采用对应链的费用模型参数
"txFeeLevel":"MIDDLE",
// 调用方负责生成,并确保唯一
"customerRefId":"a1ef66******92e723",
}

审批和签名

交易任务创建后,将根据您的策略决定,此笔交易是由人工审核签名还是由 API Co-Signer 自动化审核签名。

交易创建后,Safeheron 手机 App 会收到推送通知,并且代办任务列表会显示此笔待审核状态的交易,审核通过后,由最后一个审批人的 App 参与完成签名。