主题(Topic)与订阅快速指南
说明:本页说明如何创建监控区块链交易事件的 topic,并为该 topic 配置 webhook 回调地址。topic 由「交易类型」与一组参数过滤条件组成(如收款方、智能合约参数等)。
1. 概念
- Topic:事件类型,可以通过定义某个参数的确定值来过滤,或不设置以实现通配匹配
- 回调地址(Endpoint):接收订阅事件发生时平台发出的 webhook 的用户服务地址;如果连续三次用户的服务无法访问,则按照一次计费
- 通知:当匹配到事件时,平台向该地址发送 HTTP POST(JSON)通知。
2. 创建 Topic
- VSYS 链的网络:目前支持 testnet 和 mainnet
- 事件类型(event_type):
BlockAppended
:新增区块事件;StatusUpdated
:交易/账户额度状态发生变化。 - Topic 支持的交易类型:目前常见有
PaymentTransaction
(支付)和ExecuteContract
(合约执行) - 回调地址(webhook_url):接收 POST 的完整 URL
Topic Name 结构
智能合约执行事件的 Topic 示例:
/chain/vsys/network/mainnet/event_type/StatusUpdated/transaction_type/ExecuteContract/contract_id/CC4ZDgQHueEokwyW8mXPmSMWddkCcRznszA/contract_type/TokenContract/function_index/3/function/send/contract_sender/*/contract_recipient/AR3WgoYsrHwxTwMwygGADphNXiHy4UsMPfv
该topic定义的事件为:在 VSYS mainnet 上订阅 StatusUpdated 事件中 ExecuteContract 类型的交易,针对合约 CC4ZDgQHueEokwyW8mXPmSMWddkCcRznszA
(TokenContract)第3号函数 send,接收者为 AR3WgoYsrHwxTwMwygGADphNXiHy4UsMPfv
,发送者不限。
各路径段说明:
/chain/vsys
: 表示区块链类型为 VSYS。以后可能支持其他的区块链类型/network/mainnet
: 表示网络为主网(不是测试网)。/event_type/StatusUpdated
: 事件类型为StatusUpdated
,通常表示交易/事件的状态发生变化(如从 pending 到 confirmed、失败等)。/transaction_type/ExecuteContract
:交易类型为合约执行(ExecuteContract),表示由合约调用产生的交易事件。/contract_id/CC4ZDgQHueEokwyW8mXPmSMWddkCcRznszA
:合约 ID(合约地址),仅匹配该合约产生的事件。/contract_type/TokenContract
:合约类别为 TokenContract(代币合约),用于区分合约实现类型。/function_index/3
:函数索引为 3(合约函数可以通过索引编号),与/function/send
等价,指向同一个函数。/function/send
:明确函数名为send
(发送 Token)。此元素之后通常跟随该函数调用的参数过滤字段。/contract_sender/*
:合约内的发送者使用通配符*
,表示匹配任意合约调用者;如需限定某个发送者,将*
替换为具体地址。/contract_recipient/AR3WgoYsrHwxTwMwygGADphNXiHy4UsMPfv
:指定合约接收者地址,仅匹配发送给该接收者的事件。注意:
- 函数名/索引与后续的参数键值对共同定义精确匹配规则;参数可为精确值或通配符。
- 若需匹配多个可能值,请使用平台支持的多值匹配或创建多个 topic。
普通支付事件:
/chain/vsys/network/mainnet/event_type/StatusUpdated/transaction_type/Payment/sender/*/recipient/AR3WgoYsrHwxTwMwygGADphNXiHy4UsMPfv
对应的transaction_type
是Payment,付款人和收款人参数对应是sender和recipient,可以为精确值或者通配符,但是必须有一个是有精确值的
新增区块事件:
/chain/vsys/network/mainnet/event_type/BlockAppended
3. 过滤字段建议
- 标准交易字段:
sender
,recipient
- 合约调用:
contractID
(合约ID)、function
(方法名)、contract_sender
(合约转账发送人),contract_receipient
(合约转账接收人),caller
(调用该合约的钱包地址或者合约ID) - 支持嵌套与数组索引:用点号与中括号访问
4. 回调(Webhook)格式示例
POST body(application/json):
{
"timestamp": 1234567890,
"count": 1,
"events": [
{
"type": 3,
"uuid": "testing-uuid-totaly-notfake",
"payload": {
"constract": false,
"address": "really-real-address",
"balanceDiff": 30,
"newBalance": 40,
"sourceTxs": [
{
"type": 2,
"id": "36Yr41ZgZixZoJLWczHiHBNsFFZdkvSgMpRBmTUdUZPc",
"recipient": "ATrBCSLCVZn3wev8Hx7iybANHrmBdCn8uQ7",
"proofs": [{
"proofType": "Curve25519",
"publicKey": "RKzKv6ZFyudJ3nBPguhervM7kDri5KpjHzR9DNupJ9U",
"address": "ATrBCSLCVZn3wev8Hx7iybANHrmBdCn8uQ7",
"signature": "4gUZVwX5KAbPxamskyccPnZEX9swYC9Xo2SmfTGhaNMXek9w2J4FNwHigctaZiM9P1RwSwcm6faB6yYbkR9B7Pyi"
}],
"timestamp": 1551842469000234562,
"amount": 1000,
"height": 2075349,
"status": "Success",
"feeCharged": 0,
"attachment": "62fb634f8c149c5bcab5587c;CnDYHs3vqBXyXFp3dDUvz9iiTgWEqioamoptTEgt7QR8"
}
],
"sourceBlocks": {
"version": 9,
"timestamp": 0,
"reference": "fake-reference",
"SPOSConsensus": {
"mintTime": 0,
"mintBalance": 20
},
"resourcePricingData": {
"computation": 300,
"storage": 4096,
"memory": 512,
"randomIO": 300,
"sequentialIO": 3000
},
"TransactionMerkleRoot": "IDKWhatTheHellIsThis",
"transactions": [
{
"type": 2,
"id": "36Yr41ZgZixZoJLWczHiHBNsFFZdkvSgMpRBmTUdUZPc",
"recipient": "AU7nJLcT1mThXGTT1KDkoAtfPzc82Sgay1V",
"proofs": [{
"proofType": "Curve25519",
"publicKey": "RKzKv6ZFyudJ3nBPguhervM7kDri5KpjHzR9DNupJ9U",
"address": "ATrBCSLCVZn3wev8Hx7iybANHrmBdCn8uQ7",
"signature": "4gUZVwX5KAbPxamskyccPnZEX9swYC9Xo2SmfTGhaNMXek9w2J4FNwHigctaZiM9P1RwSwcm6faB6yYbkR9B7Pyi"
}],
"timestamp": 1551842469000234562,
"amount": 100,
"height": 2075349,
"status": "Success",
"feeCharged": 0
}
],
"generator": "testgen",
"signature": "testsig",
"fee": 30,
"blocksize": 256,
"height": 666,
"transaction count": 1
}
},
"referenceRules": {
"abc": 123
}
}
]
}
建议在服务器端验证:
- 检查 HTTP 状态码(平台通常要求 200 OK)
- 验证回调签名:基于 CanonicalRequest(包含 "x-sdk-time"、"User-Agent" 等字段)生成签名,并使用订阅方的公钥(public-key)进行校验。
- 避免处理重复通知(使用 tx_hash 去重)
5. 常见场景示例
- 仅监听发送到某地址的转账:
/transaction_type/Payment/sender/*/recipient/AR3WgoYsrHwxTwMwygGADphNXiHy4UsMPfv
- 监听特定智能合约方法(如 send token)且接收者参数为某用户:
/chain/vsys/network/mainnet/event_type/StatusUpdated/transaction_type/ExecuteContract/contract_id/CC4ZDgQHueEokwyW8mXPmSMWddkCcRznszA/contract_type/TokenContract/function_index/3/function/send/contract_sender/*/contract_recipient/AR3WgoYsrHwxTwMwygGADphNXiHy4UsMPfv
- 多条件:
/chain/vsys/network/mainnet/event_type/StatusUpdated/transaction_type/ExecuteContract/contract_id/CC4ZDgQHueEokwyW8mXPmSMWddkCcRznszA/contract_type/TokenContract/function_index/3/function/send/contract_sender/ARD6RdjBMjJRfQcdTaxc7hSesFcRnWGGQLB/contract_recipient/AR3WgoYsrHwxTwMwygGADphNXiHy4UsMPfv
6. 操作流程小结
- 在控制台或 API 创建 topic(指定 tx_type、filters、webhook_url)
- 验证 webhook 接收能力(返回 200,支持 HTTPS)
- 上线后观察通知日志,并按需调整 filters
如需示例 API 调用格式或更多字段说明,请告知平台 API(REST/Web UI)偏好。
使用流程
激活服务账户
使用前node watcher前需要激活账户(账户基于钱包地址),新的激活的账户。点击register 按钮后就可以激活服务开始使用。如果账户已经激活,页面会显示账户在此服务中的资源使用信息。
订阅新增block 事件
只需要选择对应网络,并且设置好接收webhook的端点地址,描述信息可以选填用来标记和描述使用信息。现在支持VSYS的testnet 和 mainnet网络。
订阅支付事件
该事件是VSYS COIN的支付事件,需要在Transaction Type
列表中选择 PaymentTransaction
。Sender 和Receipient 作为coin 支付事件的过滤条件,两个参数必须保证一个为有效值。
订阅智能合约执行事件
当前支持的智能合约类型有:AtomicSwapContract
,TokenContract
和SplitTokenContract
。首先需要输入在所选择网络中存在的Contract的ID,如果是合法的Contract,将会在Functions的select 里面显示其支持的Function。
Function是必选项,选择之后下方组建会显示Function支持的过滤参数类型,必须保证有一个选项是有效的。
订阅管理
用户创建订阅后可以通过订阅列表右侧的Actions 栏的按钮管理已经创建的订阅主题
现在支持的管理操作:
- 开启和关闭订阅:用户可以打开或者关闭订阅。关闭后webhook 将停止发送,该主题订阅在关闭期间不再计费。订阅开启之后系统开始发送开启之后订阅主题对应的事件webhook,关闭期间的订阅事件将不会发送。
- 删除订阅: 将订阅从系统中删除,webhook将不再发送
- 更新订阅信息: 更新订阅只能修改webhook 接收地址信息和订阅描述信息
← 服务充值