Diem 框架 VASP 模块深入解析:Parent/Child 双层账户体系与链上合规账户管理

原创2026-09-21 12:13:301,652 阅读
文章标签:区块链金融科技

Diem 框架 VASP 模块深入解析:Parent/Child 双层账户体系与链上合规账户管理

导读

VASP(Virtual Asset Service Provider,虚拟资产服务提供商)是 Diem 区块链上承担合规资金托管的一类核心账户。本文以 VASP.md 文档为主体,结合其 Move 源码 VASP.move 及 DiemAccount.move、DualAttestation.move 等调用方实现,系统讲解 VASP 的两层账户层级(Parent VASP 与 Child VASP)、账户凭据发布流程、常用查询 API、错误码约定以及 Move Prover 形式化规范。读完本文,你将掌握如何在 Diem 框架中创建与管理 VASP 账户、如何通过 VASP 模块的 API 判断账户归属与层级关系,并理解账户限额(Account Limits)与双签证明(Dual Attestation)等合规机制如何建立在 VASP 层级之上。


一、模块定位:链上的两层 VASP 账户层级

VASP 模块(0x1::VASP)是 Diem 区块链上一种"持有余额型账户"(balance-holding account)的管理模块。官方文档对它的定位非常明确:

A VASP is one type of balance-holding account on the blockchain. VASPs form a two-layer hierarchy. The main account, called a "parent VASP" and a collection of "child VASP"s. This module provides functions to manage VASP accounts.

也就是说,一个 VASP 实体在链上由一个 Parent VASP 主账户 和若干个 Child VASP 子账户 组成两层结构:

  • Parent VASP:VASP 实体的唯一根账户,持有 ParentVASP 资源,保存该 VASP 的子账户数量等元数据,是对外进行 off-chain 协议交互的锚点;
  • Child VASP:依附于某个 Parent 的子账户,通过 ChildVASP 资源记录其父账户地址,用于承载实际业务资金流动。

这一设计将"企业身份"与"日常运营账户"解耦:合规身份、限额窗口、双签证明等都以 Parent 为粒度统一管理,而业务上可以使用多个 Child 账户进行分账、流水隔离。

从源码看,该模块依赖如下标准库与框架模块(见 VASP.move):

use DiemFramework::DiemTimestamp;   // 链运行时间戳与"链处于运行中"断言
use DiemFramework::Roles;           // 角色(TreasuryCompliance / ParentVASP / ChildVASP)
use DiemFramework::AccountLimits;   // 账户限额窗口(Window<CoinType>)
use Std::Errors;                    // 标准错误码构造
use Std::Signer;                    // signer 地址提取
friend DiemFramework::DiemAccount;  // 仅允许 DiemAccount 模块调用发布函数

值得注意的关键点是 friend DiemFramework::DiemAccount:两个"凭据发布"函数(publish_parent_vasp_credential 与 publish_child_vasp_credential)均为 public(friend) 可见性,只能被 DiemAccount 模块调用,普通账户或脚本无法直接发布 VASP 凭据,从而把 VASP 账户的创建入口收敛到统一账户管理模块中。


二、核心数据结构:ParentVASP 与 ChildVASP

2.1 Resource ParentVASP

每个 VASP 拥有一个唯一的根账户,该账户下存放 ParentVASP 资源:

struct ParentVASP has key {
    num_children: u64   // 该 Parent 已创建的子账户数量
}

字段含义:

字段 类型 说明
num_children u64 Parent VASP 已创建的子账户数量,发布时初始化为 0,每成功创建一个 Child 则自增 1

从源码结构看,ParentVASP 资源只保存子账户计数,其"全局唯一名称"(globally unique name)与 off-chain 协议所需的元数据并不存放在本资源内——实际由 DualAttestation::publish_credential 发布 Credential 资源承载(见下文 DiemAccount.move 调用链)。

2.2 Resource ChildVASP

子账户通过 ChildVASP 资源记录归属关系:

struct ChildVASP has key {
    parent_vasp_addr: address   // 父 VASP 账户地址
}

该资源是"子账户→父账户"的单向引用,且一旦发布不可修改(由模块规格中的 Immutability of Parent Address 不变量保证)。


三、常量与错误码约定

模块定义了 4 个错误码常量与 1 个数量上限常量:

常量 值 触发场景
EPARENT_OR_CHILD_VASP 0 目标地址上已存在 ParentVASP 或 ChildVASP 资源(状态不符,配合 Errors::already_published 使用)
ETOO_MANY_CHILDREN 1 创建新 Child 会导致 Parent 的子账户数超过上限(配合 Errors::limit_exceeded)
ENOT_A_VASP 2 地址既不是 Parent 也不是 Child VASP(配合 Errors::invalid_argument)
ENOT_A_PARENT_VASP 3 创建 Child 的调用者不是 Parent VASP(配合 Errors::invalid_argument)
MAX_CHILD_ACCOUNTS 65536(2^16) 单个 Parent VASP 最多可创建的子账户数量

其中 MAX_CHILD_ACCOUNTS: u64 = 65536; // 2^16,即一个 Parent 名下账户总数理论上限为 65537(子账户 + 自身)。这一上限在发布 Child 凭据时被强制检查(见下文)。


四、账户凭据发布:如何创建 Parent 与 Child VASP

4.1 publish_parent_vasp_credential:创建 Parent VASP

public(friend) fun publish_parent_vasp_credential(vasp: &signer, tc_account: &signer)

在 vasp 签名者地址下创建一个新的 ParentVASP 资源。完整实现(VASP.move):

public(friend) fun publish_parent_vasp_credential(vasp: &signer, tc_account: &signer) {
    DiemTimestamp::assert_operating();                       // 链必须处于运行期
    Roles::assert_treasury_compliance(tc_account);           // tc_account 必须是 TreasuryCompliance
    Roles::assert_parent_vasp_role(vasp);                    // vasp 必须已被授予 ParentVASP 角色
    let vasp_addr = Signer::address_of(vasp);
    assert(!is_vasp(vasp_addr), Errors::already_published(EPARENT_OR_CHILD_VASP));
    move_to(vasp, ParentVASP { num_children: 0 });           // 发布资源,子账户数初始化为 0
}

执行流程与中止条件:

  1. 运行期检查:DiemTimestamp::assert_operating() 保证只有在链进入正常运营状态(非创世/暂停期)时才能创建 VASP;
  2. 双角色校验:tc_account 必须具有 Treasury Compliance(财库合规)角色,vasp 必须已具有 ParentVASP 角色——角色由 Roles.move 模块管理;
  3. 幂等性保护:如果该地址上已经存在任一 VASP 资源(Parent 或 Child),则以 Errors::ALREADY_PUBLISHED 错误中止,防止重复发布;
  4. 发布资源:move_to 写入 ParentVASP { num_children: 0 }。

形式化规格(Specification)通过 PublishParentVASPEnsures schema 承诺:调用成功后 is_parent(vasp_addr) 为真,且 spec_num_children(vasp_addr) == 0。

4.2 publish_child_vasp_credential:创建 Child VASP

public(friend) fun publish_child_vasp_credential(parent: &signer, child: &signer) acquires ParentVASP

为 parent 创建一个 Child VASP 资源。完整实现(VASP.move):

public(friend) fun publish_child_vasp_credential(
    parent: &signer,
    child: &signer,
) acquires ParentVASP {
    Roles::assert_parent_vasp_role(parent);                  // parent 必须是 ParentVASP 角色
    Roles::assert_child_vasp_role(child);                    // child 必须是 ChildVASP 角色
    let child_vasp_addr = Signer::address_of(child);
    assert(!is_vasp(child_vasp_addr), Errors::already_published(EPARENT_OR_CHILD_VASP));
    let parent_vasp_addr = Signer::address_of(parent);
    assert(is_parent(parent_vasp_addr), Errors::invalid_argument(ENOT_A_PARENT_VASP));
    let num_children = &mut borrow_global_mut<ParentVASP>(parent_vasp_addr).num_children;
    // 若创建该子账户会使 Parent 超出上限则中止
    assert(*num_children < MAX_CHILD_ACCOUNTS, Errors::limit_exceeded(ETOO_MANY_CHILDREN));
    *num_children = *num_children + 1;                       // 原子地自增子账户计数
    move_to(child, ChildVASP { parent_vasp_addr });          // 写入子账户资源
}

关键检查点:

  1. 角色检查:parent 必须具备 ParentVASP 角色,child 必须具备 ChildVASP 角色(角色发布由 DiemAccount 调用 Roles::new_child_vasp_role 完成);
  2. 地址冲突检查:child 地址上不能已有任何 VASP 资源;
  3. 父账户存在性检查:parent 地址上必须真实存在 ParentVASP 资源,否则以 ENOT_A_PARENT_VASP 中止;
  4. 数量上限检查:num_children < MAX_CHILD_ACCOUNTS(65536),超过则抛 Errors::LIMIT_EXCEEDED;
  5. 原子性:先对 borrow_global_mut<ParentVASP> 取得的计数执行自增,再 move_to 发布子资源,两者在同一交易内原子生效。

4.3 与 DiemAccount 的配合:真实创建入口

publish_*_vasp_credential 只是"凭据发布"这一环。在框架中,账户的真正创建由 DiemAccount 模块的公开函数完成,VASP 模块函数作为其内部步骤被调用:

  • DiemAccount::create_parent_vasp_account<Token>(DiemAccount.move):

    • 参数:creator_account(须为 TreasuryCompliance)、new_account_address、auth_key_prefix、human_name、add_all_currencies;
    • 调用链:Roles::new_parent_vasp_role → VASP::publish_parent_vasp_credential → Event::publish_generator → DualAttestation::publish_credential(写入 VASP 的人类可读名称 human_name)→ VASPDomain::publish_vasp_domains → make_account → add_currencies_for_account。
  • DiemAccount::create_child_vasp_account<Token>(DiemAccount.move):

    • 参数:parent(须为 ParentVASP)、new_account_address、auth_key_prefix、add_all_currencies;
    • 调用链:DiemTimestamp::assert_operating → Roles::assert_parent_vasp_role(parent) → Roles::new_child_vasp_role → VASP::publish_child_vasp_credential → Event::publish_generator → make_account → add_currencies_for_account。

因此,业务方不应直接调用 VASP 模块的 public(friend) 函数,而应通过 DiemAccount 的这两个公开入口创建账户。这也是 friend 声明存在的意义:把凭据发布权限限定给 DiemAccount,保证 VASP 创建过程(角色、凭据、事件、账户结构、币种余额)完整且有序。


五、公开查询 API:层级判定与地址解析

VASP 模块提供了一组纯查询(只读)函数,供其他模块判断账户属性:

5.1 层级判定三件套:is_parent / is_child / is_vasp

三者实现极为简单,本质是资源存在性检查:

public fun is_parent(addr: address): bool { exists<ParentVASP>(addr) }
public fun is_child(addr: address): bool  { exists<ChildVASP>(addr) }
public fun is_vasp(addr: address): bool   { is_parent(addr) || is_child(addr) }
  • is_parent:地址上存在 ParentVASP 资源;
  • is_child:地址上存在 ChildVASP 资源;
  • is_vasp:二者任一成立。

规格中它们被标记为 pragma opaque = true 且 aborts_if false,即纯函数、永不中止。

5.2 parent_address:统一解析"父账户地址"

public fun parent_address(addr: address): address acquires ChildVASP
  • 若 addr 是 Parent VASP,返回自身地址;
  • 若 addr 是 Child VASP,返回其 ChildVASP.parent_vasp_addr;
  • 否则以 Errors::invalid_argument(ENOT_A_VASP) 中止。
public fun parent_address(addr: address): address acquires ChildVASP {
    if (is_parent(addr)) {
        addr
    } else if (is_child(addr)) {
        borrow_global<ChildVASP>(addr).parent_vasp_addr
    } else {
        abort(Errors::invalid_argument(ENOT_A_VASP))
    }
}

这是 VASP 模块中被引用最频繁的工具函数——账户限额、双签证明都以"归一到父账户"的方式复用此函数(见第六节)。

5.3 is_same_vasp:判断是否属于同一 VASP 实体

public fun is_same_vasp(addr1: address, addr2: address): bool acquires ChildVASP {
    is_vasp(addr1) && is_vasp(addr2) && parent_address(addr1) == parent_address(addr2)
}

两个地址必须都是 VASP,且 parent_address 解析结果相同,才判定为同一 VASP 实体。该函数被 DiemAccount::should_track_limits_for_account 用于区分"VASP 内部转账"与"跨 VASP 转账"(见下文)。

5.4 num_children:查询子账户数量

public fun num_children(addr: address): u64 acquires ChildVASP, ParentVASP {
    *&borrow_global<ParentVASP>(parent_address(addr)).num_children
}
  • 传入 Parent 地址:返回其自身 num_children;
  • 传入 Child 地址:先经 parent_address 解析出父账户,再返回父账户的 num_children;
  • 该 VASP 名下账户总数为 num_children() + 1(含 Parent 自身);
  • 若 addr 既非 Parent 也非 Child,则以 Errors::INVALID_ARGUMENT 中止(规格中 aborts_if !is_vasp(addr))。

5.5 has_account_limits:限额窗口检查

public fun has_account_limits<CoinType>(addr: address): bool acquires ChildVASP {
    AccountLimits::has_window_published<CoinType>(parent_address(addr))
}

当 addr 是 Parent 或 Child VASP 时,返回其父账户是否已发布 AccountLimits<CoinType> 限额窗口资源。底层依赖 AccountLimits.move 的 has_window_published,即检查父账户上是否存在 Window<CoinType> 资源。


六、VASP 模块在合规体系中的实际调用

VASP 模块并非孤立存在,它是 Diem 合规账户体系的基石。以下调用关系均可从源码确认:

6.1 账户限额(Account Limits)的判定与记录

在 DiemAccount.move 中:

  • has_published_account_limits<Token>(addr):若 VASP::is_vasp(addr) 为真,则委托给 VASP::has_account_limits<Token>(addr)(即检查父账户的限额窗口);否则直接查该地址自身的 Window;

  • should_track_limits_for_account<Token>(payer, payee, is_withdrawal):判定是否需要对一笔转账记录限额。其逻辑是:

    • 出账方(withdrawal)被追踪的条件:has_published_account_limits(payer) && VASP::is_vasp(payer) && !VASP::is_same_vasp(payer, payee);
    • 入账方(deposit)同理。

    关键语义:VASP→任意、任意→VASP 的转账在 VASP(父账户粒度)上记账,但同一 VASP 内部(is_same_vasp 为真)的转账不记入限额——这解释了为什么需要 is_same_vasp 与 parent_address。

  • 在 deposit 内部(DiemAccount.move),若应追踪限额,则调用 AccountLimits::update_deposit_limits<Token>(deposit_value, VASP::parent_address(payee), ...)——限额窗口统一挂在父账户地址上,子账户的入账都归一计入父账户窗口。

6.2 双签证明 / 旅行规则(Dual Attestation)

在 DualAttestation.move 中:

  • credential_address(addr):if (VASP::is_child(addr)) VASP::parent_address(addr) else addr——子账户的合规凭据统一到父账户上读取;
  • dual_attestation_required<Token>(payer, payee, deposit_value):当转账金额超过旅行规则限额(travel rule limit)时,若 VASP::is_vasp(payer) && VASP::is_vasp(payee) && VASP::parent_address(payer) != VASP::parent_address(payee),则判定需要双签证明。同一 VASP 内部或 VASP 与非 VASP 之间的转账不触发双签要求。

可以看到,"同一 VASP 实体"的判定(is_same_vasp / parent_address 相等性)贯穿限额与双签两大合规机制,是 VASP 层级设计的直接收益。


七、Move Prover 形式化规格:模块级不变量

VASP 模块附带完整的 Move Prover 规格(VASP.move),将层级关系固化为四条可被形式化验证的不变量:

7.1 Persistence of parent and child VASPs(持久性)

invariant update forall addr: address where old(is_parent(addr)):
    is_parent(addr);
invariant update forall addr: address where old(is_child(addr)):
    is_child(addr);

任何状态变更前后,已是 Parent/Child VASP 的地址必须保持其身份不变——VASP 资源一经发布永不删除。

7.2 Existence of Parents(父账户必然存在)

invariant
    forall child_addr: address where is_child(child_addr):
        is_parent(global<ChildVASP>(child_addr).parent_vasp_addr);

每个 Child VASP 的 parent_vasp_addr 指向的地址上必然存在 ParentVASP 资源,杜绝悬空引用。

7.3 Creation of Child VASPs(子账户只能由 Parent 创建)

apply ChildVASPsDontChange to *<T>, * except publish_child_vasp_credential;
apply NumChildrenRemainsSame to * except publish_child_vasp_credential;

除 publish_child_vasp_credential 外的所有函数都不能新增/删除 ChildVASP 资源(ChildVASPsDontChange schema),也不能改变任何 Parent 的 num_children(NumChildrenRemainsSame schema)。即:只有父 VASP 调用该函数才能创建子账户,子账户数量只能通过添加子账户的方式增加。

7.4 Immutability of Parent Address(父地址不可变)

invariant update
    forall a: address where old(is_child(a)): spec_parent_address(a) == old(spec_parent_address(a));

Child VASP 中存储的父地址在资源生命周期内永不改变,保证了归属关系的长期稳定——这是限额窗口与双签凭据能够持久挂在父账户上的前提。


八、小结:VASP 模块的设计要点

设计点 机制 依据
两层账户层级 Parent 持有 num_children 计数,Child 持有 parent_vasp_addr 引用 VASP.move
创建权限收口 public(friend) + friend DiemAccount,凭据发布只能经 DiemAccount::create_*_vasp_account VASP.move、DiemAccount.move
子账户数量上限 MAX_CHILD_ACCOUNTS = 65536,发布时强制检查 VASP.move
合规粒度归一 限额窗口、双签凭据均以 parent_address 解析后的父账户为锚点 DiemAccount.move、DualAttestation.move
内部转账豁免 is_same_vasp 判定同一实体,内部转账不记限额、不触发双签 VASP.move
形式化保证 持久性、父账户存在性、创建唯一入口、父地址不可变四条不变量 VASP.move

如需继续深入,推荐按以下顺序阅读仓库源码:

  1. VASP.move——本文主体模块的完整实现与规格;
  2. DiemAccount.move——VASP 账户创建与限额记录的真实调用方(重点看第 1390–1500 行);
  3. DualAttestation.move——双签证明如何基于 parent_address / is_same_vasp 判定;
  4. AccountLimits.move——限额窗口 Window<CoinType> 的发布与 has_window_published 实现;
  5. 自动生成的模块文档 VASP.md,其中包含与源码一一对应的函数签名与规格说明。
登录后查看全文
diem