主题(Topic)与订阅快速指南

说明:本页说明如何创建监控区块链交易事件的 topic,并为该 topic 配置 webhook 回调地址。topic 由「交易类型」与一组参数过滤条件组成(如收款方、智能合约参数等)。

1. 概念

  • Topic:事件类型,可以通过定义某个参数的确定值来过滤,或不设置以实现通配匹配
  • 回调地址(Endpoint):接收订阅事件发生时平台发出的 webhook 的用户服务地址;如果连续三次用户的服务无法访问,则按照一次计费
  • 通知:当匹配到事件时,平台向该地址发送 HTTP POST(JSON)通知。

2. 创建 Topic

  1. VSYS 链的网络:目前支持 testnet 和 mainnet
  2. 事件类型(event_type):BlockAppended:新增区块事件;StatusUpdated:交易/账户额度状态发生变化。
  3. Topic 支持的交易类型:目前常见有 PaymentTransaction(支付)和 ExecuteContract(合约执行)
  4. 回调地址(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. 操作流程小结

  1. 在控制台或 API 创建 topic(指定 tx_type、filters、webhook_url)
  2. 验证 webhook 接收能力(返回 200,支持 HTTPS)
  3. 上线后观察通知日志,并按需调整 filters

如需示例 API 调用格式或更多字段说明,请告知平台 API(REST/Web UI)偏好。

使用流程

激活服务账户

使用前node watcher前需要激活账户(账户基于钱包地址),新的激活的账户。点击register 按钮后就可以激活服务开始使用。如果账户已经激活,页面会显示账户在此服务中的资源使用信息。

avtivate account

订阅新增block 事件

只需要选择对应网络,并且设置好接收webhook的端点地址,描述信息可以选填用来标记和描述使用信息。现在支持VSYS的testnet 和 mainnet网络。 sub block append

订阅支付事件

该事件是VSYS COIN的支付事件,需要在Transaction Type列表中选择 PaymentTransaction。Sender 和Receipient 作为coin 支付事件的过滤条件,两个参数必须保证一个为有效值。 sub payment

订阅智能合约执行事件

当前支持的智能合约类型有:AtomicSwapContractTokenContractSplitTokenContract。首先需要输入在所选择网络中存在的Contract的ID,如果是合法的Contract,将会在Functions的select 里面显示其支持的Function。

sub contract: Input ID

Function是必选项,选择之后下方组建会显示Function支持的过滤参数类型,必须保证有一个选项是有效的。 sub contract: Set filter for function

订阅管理

用户创建订阅后可以通过订阅列表右侧的Actions 栏的按钮管理已经创建的订阅主题 manange sub 现在支持的管理操作:

  • 开启和关闭订阅:用户可以打开或者关闭订阅。关闭后webhook 将停止发送,该主题订阅在关闭期间不再计费。订阅开启之后系统开始发送开启之后订阅主题对应的事件webhook,关闭期间的订阅事件将不会发送。
  • 删除订阅: 将订阅从系统中删除,webhook将不再发送
  • 更新订阅信息: 更新订阅只能修改webhook 接收地址信息和订阅描述信息 update sub
上次更新: 2025/10/16 上午6:08:28