On this page
  1. §0 The area in one paragraph
  2. 1. The group address, the tables and the resolution rule
  3. 2. The bodies and the consent proof
  4. 3. LinkAccount (55)
  5. 4. UnlinkAccount (56)
  6. 5. SetMemberPermissions (57) and TransferGroupControl (58)
  7. 6. What joining moves
  8. 7. The join blockers
  9. 8. A member's transaction: the gate and the limit
  10. 9. Rent, dissolution and the views
  11. 10. Ledger rows and the consensus/local split

18 — Account groups: LinkAccount, UnlinkAccount, SetMemberPermissions, TransferGroupControl

Edition 0.6.1 · verified against the reference implementation, version 0.6.1

Out of scope the canonical account key and address types (01); signature verification per address type (02); the multisig address derivation (12 §9); the fee floor and refund (04); the rent step that prunes and dissolves (13 §9); the pull-at-fire schedule's member gate (08 §6); split and transact policies (08); snapshots (26)

§0 The area in one paragraph

A group is one account reachable at many addresses. Its balance, tokens and every object it owns live on a keyless group address derived from the hash of the transaction that founded it; every balance read and write on a member address resolves to that row, and a transaction signed by a member is executed with the group address as sender. The controller is the member that manages the group: it links addresses that consent by signing a chain-bound digest, sets each member's right to spend (none, unlimited, or a ZBC limit per period, with a separate bit for tokens), removes members, and hands control to another member who consents the same way. Joining moves everything the address owns into the group; leaving returns nothing and resets the address to a fresh, empty account. A member's transaction that the controller has not permitted, or that would exceed its limit, is refused at admission and invalidates the block that carries it; the limit is enforced on what the transaction actually took, by running it inside a savepoint. The group pays account rent plus a storage rent on the weight of its record; a group that cannot pay is pruned and dissolved. Everything here is consensus state except the views.

1. The group address, the tables and the resolution rule

Purpose. The identity of a group and how every other mechanism sees its members.

Inputs. The founding LinkAccount's transaction hash; the two tables below.

Output and effect. Group address = 00000000 ‖ SHA3-256("ZBC-GROUP" ‖ hash) (36 bytes; a ZBC-typed address nobody holds the key for). Tables, both versioned (07 §2): account_group(group_address, block_height, latest, controller_address, link_seq, status (1 active / 0 dissolved), created_height), key (group_address, block_height); account_group_member(member_address, block_height, latest, group_address, active, flags, spend_limit, period_blocks, window_start, window_spent, linked_height), key (member_address, block_height); addresses are typed account bytes (01; a bare 32-byte key is no account); an inactive member row has an empty group_address. Types: link_seq, flags, status, active small unsigned integers; spend_limit and window_spent signed 64-bit; period_blocks, window_start, linked_height, created_height, heights unsigned 32-bit. Reads: a group by address and a member by address (each its latest row, or its newest row at or below a height); the active members of a group in ascending member_address. A rollback to H deletes the rows above H. Resolution: the balance holder of a = the group address when a is an active member, else a. Every account read, every account write, every credit and every token balance read and write (14 §1) go through it, so a member holds nothing of its own. The same-account test same(a, b) = a == b (bytes), or, when at least one is a member, equal balance holders; it is how authority named on a member (escrow approver or recipient, swap counterparty, app player, schedule recipient, pending release authority, longevity owner) is honoured for the member acting as its group. The nonce and the rent clock stay per address (a member's first spend does not arm rent, 13 §9).

How to compute it. As stated.

Rule activation. account_groups (active from height 0 on every chain): the four types exist and members resolve from it. balance_credit_full_row (likewise) routes the per-block credits through the same resolution (07).

Rejections and errors. None.

Vector. computed.

  • Input: a founding LinkAccount whose transaction hash is 32 × AB.
  • Expected output: the group address 0000000026089158C66E9217872CC1780CED187CE334413BA93844EDD2813C77BDF13E67 = 00000000 ‖ SHA3-256("ZBC-GROUP" ‖ 32 × AB) ("ZBC-GROUP" = 9 ASCII bytes, no terminator).
  • computed (the view; account_group_max_members 100 in both live genesis files and the mainnet template): for the TestNet treasury GET /api/v1/accounts/00000000120ee4ca9d258d75656901ec4837373e07763369ad75ed8d63fa31c7e0b7e807/group answers {"address":"00000000120ee4ca…e807","role":"none","max_members":100} while it is in no group.

Test cases · §1

2 cases · 2 valid · 1 reference

The group address of a founding link whose hash is 32 bytes of AB18-1-addressvalid

Loading the test widget…

The group view of the TestNet treasury while it is in no group18-1-no-groupvalidreference

account_group_max_members is 100 in both live genesis files and the mainnet template.

A stated value: there is nothing to compute. A compatible node shows the same value.

value
{"address":"00000000120ee4ca9d258d75656901ec4837373e07763369ad75ed8d63fa31c7e0b7e807","role":"none","max_members":100}

Defects to match. (1) A dissolved group's row stays (status 0) and its address keeps whatever tokens and objects it held, keyless. (2) The group address is a valid payment target like any account; a payment to it needs no member.

2. The bodies and the consent proof

Purpose. The four wire formats and the digest a consenting party signs.

Inputs. Addresses in bodies are len (u8) ‖ typed address (01; a 32-byte bare key is not an address and is refused as malformed). All integers little-endian. Every body begins version (u8) = 1; a body with trailing bytes or short fields is refused.

LinkAccount (55) Bytes
version u8 = 1
member len u8 ‖ address
valid_until_height u32
link_seq u32 (the group's counter; 0 founds a group)
proof see below
UnlinkAccount (56) Bytes
version, member u8 = 1; len ‖ address
SetMemberPermissions (57) Bytes
version, member u8 = 1; len ‖ address
flags u8: bit 0 may spend; bit 1 may move tokens (needs bit 0); other bits 0
spend_limit u64 (read as i64; ≥ 0); 0 = no limit
period_blocks u32: 1…2,102,400 when spend_limit > 0, else 0
TransferGroupControl (58) Bytes
version, new_controller u8 = 1; len ‖ address
valid_until_height, link_seq u32, u32
proof see below

Proof: kind (u8) then, for kind 0 or 2, sig_len (u16, > 0) ‖ signature; for kind 1, minimum_signatures (u32) ‖ nonce (i64) ‖ n (u8, > 0) ‖ n × (len u8 ‖ participant address ‖ sig_len u16 ‖ signature, which may be empty). The digest: SHA3-256(tag ‖ genesis hash (32) ‖ len ‖ A ‖ len ‖ B ‖ valid_until (u32) ‖ link_seq (u32)) with tag ZBC-GROUP-LINK (14 ASCII bytes; A = the controller, i.e. the sender, B = the member) or ZBC-GROUP-CONTROL (17 ASCII bytes; A = the current controller, B = the new one), both as typed account bytes. The consent is checked in this order:

  1. Kind 0 or 2, when the consenting address is Ethereum- or Tron-typed (type 4 or 15): the signature must be 65 bytes ending in 27 or 28 (02), else refused.
  2. Kind 0: the consenting address's signature over the 32-byte digest, verified by its address type (02).
  3. Kind 2 (a wallet's message signature): the consenting address must be Ethereum-typed (type 4), whose signature is over "\x19Ethereum Signed Message:\n32" ‖ digest (MetaMask personal_sign), or Tron-typed (type 15), whose signature is over "\x19TRON Signed Message:\n32" ‖ digest (TronLink: TronWeb's signMessageV2, prefix ‖ decimal length ‖ message, and its older signString, the fixed …\n32 prefix ‖ message, give these same bytes for a 32-byte digest). Either is verified as an Ethereum signature: the key is recovered from keccak256(prefix ‖ digest) and its Keccak address must be the address's 20 bytes.
  4. Kind 1: the consenting address must be a multisig account; the participants (no duplicates, 1…255, none of them a full-key form, 01) with minimum_signatures (1…n) and nonce derive H (12 §9), and the typed account 00000000 ‖ H must be the consenting address (the form the chain stores; the bare H is no account); every non-empty participant signature by an Ethereum- or Tron-typed participant must end in 27 or 28 (else the whole proof is refused); every non-empty signature is then verified over the digest for its participant, and at least minimum_signatures must verify.

Output and effect. Parsed fields; a consent that verifies.

How to compute it. As stated; an address whose type cannot sign (the one list of 01: every type but 0, 1, 4, 5, 6, 7, 9, 11, 12, 13, 14, 15, 16; so 2 Empty, 3, 8, 10 and unknown types) can neither consent nor be a member, and neither can a bare 32-byte key or a full-key form (an Ethereum or Tron type followed by a 64-byte key, a Bitcoin legacy, P2PKH or P2WPKH type followed by a 33- or 65-byte key, 01): the member of LinkAccount and SetMemberPermissions, the new controller of TransferGroupControl and every participant of a kind-1 consent are refused in that form. UnlinkAccount is not refused for it, so an address linked in that form can still leave.

Rule activation. eth_signature_canonical_v (the 27/28 test of steps 1 and 4) and canonical_account_forms (the full-key refusals, the Tron form of kind 2 and the typed comparison of kind 1), both active from height 0 on every chain; otherwise none beyond §1.

Rejections and errors. "<Type>: unsupported body version", "<Type>: malformed consent proof", "<Type>: truncated body or trailing bytes"; consent (each prefixed by the type's "…: member consent: " or "…: new controller consent: ", §3, §5): "the consent signature: Ethereum signature recovery id must be 27 or 28", "the consent signature does not verify for the consenting address", "consent proof kind 2 (personal_sign) is for an Ethereum address (or, under rule canonical_account_forms, a Tron one)", "the personal_sign consent does not verify for the consenting address", "unknown consent proof kind", "multisig consent: no participants", "… threshold out of range", "… duplicate participant", "multisig consent: a participant: a full-key account form (an Ethereum or Tron key, a Bitcoin key) is not an account: no transaction can be sent from it; name the 20-byte address (rule canonical_account_forms)", "… the participants, threshold and nonce do not hash to the consenting address", "multisig consent: a participant signature: Ethereum signature recovery id must be 27 or 28", "… V valid participant signatures, M required".

Vector. computed.

  • Input: genesis hash 32 × 5A, controller A = 00000000 ‖ 32 × 11, member B = 04000000 ‖ 20 × 22 (an Ethereum account), valid_until 1,000, link_seq 0. Expected: link digest 999E96F16DB8BF3BE83B59FCE3DFC56F3CC7FA0397DC80BCBAA502F24FF66120.
  • Input: the same with tag ZBC-GROUP-CONTROL, link_seq 3. Expected: control digest 7B3637C306EFF8F6FFEFC9BC316263C292A2FBF6F4A5E01C6DBA57B70278334D.
  • Input: the vectors' identity G of 02 §1 (E003E4E3557EF19F0519BD345009DEA7FB43B3445EAA043920C5DC23B3302871, an example value: a chain uses its own genesis hash), controller 00000000120EE4CA9D258D75656901EC4837373E07763369AD75ED8D63FA31C7E0B7E807, member 00000000B6675786BEDF28B3E7DCD8BAC9BF99758B3A64604570BFFD12FD10CBF20B39EA, valid_until 20,000, link_seq 0. Expected: link digest D503C25A8D7A14E9CA38DCAD639CC4E0494A0092372FCB405051444EC490D3E9; the LinkAccount body is 01 ‖ 24 ‖ member (36) ‖ 204E0000 ‖ 00000000 ‖ 00 ‖ 4000 ‖ the member key's 64-byte Ed25519 signature over the digest (113 bytes).
  • Input: a SetMemberPermissions body for that member with flags 1, limit 50,000,000, period 1,000: 01 ‖ 24 ‖ member ‖ 01 ‖ 80F0FA0200000000 ‖ E8030000 (51 bytes).
  • Input (a Tron consent of kind 2): genesis hash 32 × 5A, controller A = 00000000 ‖ 32 × 11, the Tron key of the private key 71a02da87982b42c8ad61d5e3c30dfc20cd369b75621fc709734a44c355cfe50 (= SHA3-256("ZooBC spec vector tron consent key"), a test key), public key C74549AF6B5471375C00F48BF2871A78117B781B9D0154FBFC54230C7C8D1A6BE2688171E8DABF5E0643891613BF0C84BA94F8CFA1FD02C170D27DC4DF63BCB3, member T = 0F000000 ‖ 9C1A9D01F45581F7CB95BF81AA1A95997700A10D (type 15, the key's Keccak address), valid_until 1,000, link_seq 0. Expected: link digest 593B9F220ABADF8A96D5733A1F36C79A8077FA6F183622A25AB3B94D977AB78F; the signed payload (56 bytes) 1954524F4E205369676E6564204D6573736167653A0A3332 ‖ digest, whose Keccak-256 is 1E17891291C4AC4417F478FA95ECDB7B25EDCBCF9E51376320094BB0FB9C3B16; the signature (RFC 6979, low s) 794B89322D095E896374056A925D77680E6389F62281D377B93797AE3247901378543CDA4D13F245951A32EB454232BA2B40BB849E81F453AC29940AD4FF8D421B (v = 27; the key it recovers has the address T); the LinkAccount body (102 bytes) 01 18 0F0000009C1A9D01F45581F7CB95BF81AA1A95997700A10D E8030000 00000000 02 4100 ‖ the 65-byte signature: the consent verifies.
  • Input (a multisig consent of kind 1): the same A and genesis hash; participants P1 = 0000000041F9A78A8E744E097002DE7303FB0648F44ED0D5D3EA195ACCD8BFA7897E61F1 and P2 = 000000007D045551B600B10C872D2E53507911DC52CFE11AD3966B60ECC87C875E3BCA4E (the Ed25519 keys of the seeds SHA3-256("ZooBC spec vector multisig participant 1") and "… 2"), minimum_signatures 1, nonce 7, so the member is 00000000C5AC58F44D7B642638605B72BCCC34739F5FD4B4E5D69563F071B8F1FB07DE90 (00000000 ‖ H, 12 §9); valid_until 1,000, link_seq 0. Expected: link digest 26A7907DA15846173799482F599DA3FF04982968E4FACD694859B54CD42A7846; P1's signature over it AA9759CC18BFFDDB061DF8EECD3D6AD1BEA0DBB039BC7C10BF74A44AB954FBA3B891B946ABFF433A60F64C4113922CB367BA75A1E37D2B34064C26B204393602; the body (202 bytes) 01 24 <member> E8030000 00000000 01 01000000 0700000000000000 02 24 <P1> 4000 <P1's signature> 24 <P2> 0000: 1 valid signature of 1 required, the consent verifies.
  • Invalid input: flags 02 (tokens without spend) → "SetMemberPermissions: the token permission (bit 1) needs the spend permission (bit 0)"; a member field of 32 bytes (20 ‖ the bare key) → "LinkAccount: the member address is malformed"; a body with one trailing byte → "LinkAccount: truncated body or trailing bytes". The Tron body above with its last byte 1B replaced by 00 (the 0/1 copy of the same signature) → "LinkAccount: member consent: the consent signature: Ethereum signature recovery id must be 27 or 28". The Tron member written as its full-key form (44 ‖ 0F000000 ‖ the 64-byte public key above) → "LinkAccount: the member: a full-key account form (an Ethereum or Tron key, a Bitcoin key) is not an account: no transaction can be sent from it; name the 20-byte address (rule canonical_account_forms)". The kind-1 body with nonce 8 → "LinkAccount: member consent: multisig consent: the participants, threshold and nonce do not hash to the consenting address". All stateless: refused at admission, and a block carrying one is invalid.

Test cases · §2

15 cases · 9 valid · 6 invalid

The same with the control tag and link_seq 318-2-control-digestvalid

Loading the test widget…

The link digest of two ZooBC accounts under the vectors' identity G18-2-testnet-digestvalid

Loading the test widget…

The link digest and the signed payload of a Tron member's kind-2 consent18-2-tron-digestvalid

Loading the test widget…

The same body with the signature's last byte 1B replaced by 0018-2-tron-v00invalid

Loading the test widget…

The Tron member written as its full-key form18-2-tron-full-keyinvalid

Loading the test widget…

The link digest of the multisig member18-2-multisig-digestvalid

Loading the test widget…

The same body with nonce 818-2-multisig-nonce-8invalid

Loading the test widget…

A SetMemberPermissions body: spend, 0.5 ZBC per 1,000 blocks18-2-permissions-bodyvalid

Loading the test widget…

The token permission without the spend permission18-2-tokens-without-spendinvalid

Loading the test widget…

A member field holding a bare 32-byte key18-2-bare-memberinvalid

Loading the test widget…

A LinkAccount body with one trailing byte18-2-trailinginvalid

Loading the test widget…

Defects to match. spend_limit is read as a u64 and then tested as a signed value: a body with the top bit set is "negative" and refused.

3. LinkAccount (55)

Purpose. Found a group, or add a member to one.

Inputs. The body of §2; the sender S (canonical); the member M.

Output and effect. In order:

  1. The fee is taken from the balance holder of S (S itself for a founder; row event 1); an unaffordable fee → nothing taken.
  2. The checks of §2 and the state checks: a founder (S in no group) needs account_group_max_members ≥ 2, link_seq 0 and no blocker of §7 on itself; a controller needs link_seq = the group's counter and fewer than account_group_max_members (100 on TestNet and DevNet; compiled 100) active members; a non-controller member → refused; M must have no blocker (§7); valid_until_height ≥ the block height and ≤ height + 5,760; the consent digest must not be spent. A failure here is a paid no-op: the fee's overpay is returned to the payer (event 22) and nothing else happens.
  3. Founding: the group row (controller S, link_seq 0, status 1, created_height) is written, S's assets move into the group (§6), S becomes an active member row (flags 0, linked_height).
  4. M's assets move (§6); M becomes an active member (flags 0, no limit, linked_height = height).
  5. The group's link_seq += 1 (a founding link therefore ends at 1).
  6. The consent digest is marked spent (spent_foreign_message, 02 §9), so it never verifies again.
  7. The overpay of the fee is returned to the group (row event 22 on G).

Then the header survival (13 §1); the generic settlement of 04 §5 does not run for the four group types.

How to compute it. Stateless (admission and block validation): the texts of §2 plus "LinkAccount: the member address is malformed", "… the member address type cannot sign, so it cannot consent or be a member", "LinkAccount: the member: a full-key account form (an Ethereum or Tron key, a Bitcoin key) is not an account: no transaction can be sent from it; name the 20-byte address (rule canonical_account_forms)", "… the controller and the member are the same address", "… valid_until_height must be set", "LinkAccount: member consent: <reason>". Admission state (refused there, a paid no-op if mined): "LinkAccount: only the group's controller can link an address", "… the group is full (N addresses, the controller included)", "… link_seq X does not match the group's counter Y", "… account_group_max_members is below 2", "… a new group's link_seq is 0", "… the controller cannot found a group: <blocker>", "… the member cannot join: <blocker>", "LinkAccount: the consent expired at height H", "… the consent is valid for more than 5760 blocks", "… this consent was already used".

Rule activation. account_groups, eth_signature_canonical_v and canonical_account_forms (§2), active from height 0 on every chain.

Rejections and errors. As listed; a storage fault in the moves fails the block.

Vector. computed (TestNet).

  • Input: the founding LinkAccount of §2's TestNet vector, sent by the controller C (balance 297,449,945 + fee F, in no group) at height h ≤ 20,000 with declared fee F, the member M holding 100,000,000; the transaction hash X.
  • Expected output: G = 00000000 ‖ SHA3-256("ZBC-GROUP" ‖ X); rows: on C event 1 −F, event 48 −297,449,945; on G event 49 +297,449,945, event 49 +100,000,000 (M's balance), event 22 +(F − the floor) (the overpay); the group row (controller C, link_seq 1, status 1, created_height h); member rows for C and M (flags 0, linked_height h); the digest marked spent.
  • Invalid input: the same transaction again → "LinkAccount: this consent was already used" (or, with the counter now 1, "LinkAccount: link_seq 0 does not match the group's counter 1") at admission; a paid no-op if mined. At height 20,001 → "LinkAccount: the consent expired at height 20000".

Test cases · §3

3 cases · 1 valid · 2 invalid

C founds a group with M: what moves18-3-foundvalid

Loading the test widget…

The same link sent again18-3-againinvalid

Loading the test widget…

The link at height 20,00118-3-expiredinvalid

Loading the test widget…

Defects to match. (1) The fee of a founding link comes from the founder's own balance before the move and the overpay lands on the group. (2) A member row that leaves and re-joins keeps its old versions; linked_height is the latest join.

4. UnlinkAccount (56)

Purpose. A member leaves, or the controller removes one.

Inputs. Body of §2; S; the target T.

Output and effect. The fee from the balance holder of S (the group, for any member). Checks: T must be an active member; S must be an active member of the same group; T ≠ S needs S to be the controller; T must not be the controller. Failure → paid no-op (overpay back to the payer). Else T's member row becomes inactive (group cleared, flags, limit, period and window zeroed) and T's account row is reset to a fresh row (balance 0, nonce 0, no rent clock, no policy); T takes nothing. Overpay back to the payer (the group).

How to compute it. Stateless: "UnlinkAccount: the member address is malformed" (a full-key form, 01, is not refused here: an address that joined in that form can still leave). Admission state: "UnlinkAccount: the address is not a member of a group", "… only the controller or the member itself can remove a member" (a sender in no group, or in another group), "… the controller cannot leave; transfer control to another member first". A sender that is a member of the group is judged by the gate of §8 first: removing another member it answers "Account group: only the group's controller can remove another member" (a block carrying it is invalid). A member removing itself passes the gate whatever its permissions.

Rule activation. account_groups, active from height 0 on every chain (canonical_account_forms deliberately leaves UnlinkAccount alone).

Rejections and errors. As listed.

Vector. computed.

  • Input: UnlinkAccount (type 56) by the controller C of group G, body 01 ‖ 24 ‖ M (38 bytes), M an active member.
  • Expected output: the fee from G (event 1 on G, overpay event 22 on G); M's member row inactive (group empty, flags, limit, period, window 0); M's account row fresh (balance 0, nonce 0, no rent clock, no policy); M takes nothing.
  • Invalid input: the same body naming C itself → "UnlinkAccount: the controller cannot leave; transfer control to another member first"; sent by a third member X ≠ M → "Account group: only the group's controller can remove another member" (the gate of §8: refused at admission, and a block carrying it is invalid).

Test cases · §4

3 cases · 1 valid · 2 invalid

The controller names itself18-4-controller-leavesinvalid

Loading the test widget…

A third member removes M18-4-third-memberinvalid

Loading the test widget…

Defects to match. The fee is read from the holder before T leaves, so a member removing itself pays from the group, and the overpay also returns to the group.

5. SetMemberPermissions (57) and TransferGroupControl (58)

Purpose. The controller's two management acts.

Inputs. The bodies of §2.

Output and effect. Both: the fee from the group; S must be the controller, else a paid no-op. Permissions: the target must be an active member of this group; its flags, spend_limit and period_blocks are replaced; the window (window_start, window_spent) is kept. Control: the new controller N must be an active member of the group; link_seq must match; the consent window and spent-digest rules of §3; then the group's controller = N and link_seq += 1; the former controller's row keeps membership with flags, limit, period and window zeroed (receive-only); the control digest is marked spent. Overpay back to the group.

How to compute it. Stateless: "SetMemberPermissions: the member address is malformed", "SetMemberPermissions: the member: a full-key account form (an Ethereum or Tron key, a Bitcoin key) is not an account: no transaction can be sent from it; name the 20-byte address (rule canonical_account_forms)", "… the controller's own rights are not set by permissions", "… unknown permission bits", "… the token permission (bit 1) needs the spend permission (bit 0)", "… negative spending limit", "… a receive-only member has no limit or period", "… a spending limit needs a period of 1 to 2102400 blocks", "… a period without a limit means nothing; send 0"; "TransferGroupControl: the new controller address is malformed", "… the new controller's address type cannot sign", "TransferGroupControl: the new controller: a full-key account form (…, as above)", "… the sender is already the controller", "… valid_until_height must be set", "TransferGroupControl: new controller consent: <reason>". Admission state: "SetMemberPermissions: only the group's controller sets permissions" (a sender in no group; a member that is not the controller is answered by the gate of §8, "Account group: only the group's controller can send this transaction type for the group", and a block carrying it is invalid), "… the address is not a member of this group"; "TransferGroupControl: only the group's controller can hand over control" (a sender in no group; a member that is not the controller is answered by the gate of §8, "Account group: only the group's controller can send this transaction type for the group", and a block carrying it is invalid), "… the new controller must already be a member of the group", "… link_seq X does not match the group's counter Y", the expiry texts, "… this consent was already used".

Rule activation. account_groups, eth_signature_canonical_v and canonical_account_forms (§2), active from height 0 on every chain.

Rejections and errors. As listed.

Vector. computed.

  • Input: SetMemberPermissions (type 57) by the controller with the body of §2's vector (flags 1, limit 50,000,000, period 1,000). Expected: M's row flags 1, spend_limit 50,000,000, period_blocks 1,000, window unchanged (window_start 0, window_spent 0 for a new member).
  • Input: TransferGroupControl (type 58) to M with link_seq 1 and M's consent over the control digest. Expected: controller M, link_seq 2; C's row stays a member with flags, limit, period and window 0 (receive-only).
  • Invalid input: the permissions body sent by M (it names M) → "SetMemberPermissions: the controller's own rights are not set by permissions" (stateless: the member named is the sender; a block carrying it is invalid); a body naming another member, sent by M → "Account group: only the group's controller can send this transaction type for the group" (the gate of §8). A SetMemberPermissions body naming the Tron member of §2 in its full-key form (44 ‖ 0F000000 ‖ the 64-byte key) → "SetMemberPermissions: the member: a full-key account form (an Ethereum or Tron key, a Bitcoin key) is not an account: no transaction can be sent from it; name the 20-byte address (rule canonical_account_forms)" (stateless: a block carrying it is invalid).

Test cases · §5

6 cases · 2 valid · 4 invalid

The controller lets M spend 0.5 ZBC per 1,000 blocks18-5-permissionsvalid

Loading the test widget…

The controller hands control to M18-5-controlvalid

Loading the test widget…

M sends the permissions body18-5-permissions-by-memberinvalid

Loading the test widget…

M sends a permissions body naming X18-5-permissions-by-member-xinvalid

Loading the test widget…

A SetMemberPermissions body naming the Tron member in its full-key form18-5-permissions-full-keyinvalid

Loading the test widget…

M, not the controller, hands control to X18-5-control-by-memberinvalid

Loading the test widget…

Defects to match. A new member's first window starts at height 0, not at its first spend: with period 1,000, spends before block 1,000 share one window.

6. What joining moves

Purpose. The transfer of everything an address owns into the group.

Inputs. The joining address; the group G.

Output and effect. In this order, each as new versions at the link height: the account row: G's balance, spendable balance and prepaid storage balance += the address's (checked; "Group balance overflow" fails the block), dataset_storage_bytes added, G's rent clock armed (height + one snapshot cycle, 13 §9) when it was 0 and the balance is now > 0, G's last_billing_height taken from the address when G is new; rows event 48 (−balance on the address) and 49 (+balance on G) when the balance > 0; the address's row becomes empty with its nonce kept. Then: every positive token balance (by token id) moves to G; every token the address issued gets issuer G (14 §1); every dataset object it owns, every stored file it owns (status 0), every pending trigger or schedule it owns (08) is re-owned by G; its open swap offers and orders (15), live longevity sponsorships (13), and node, gateway, archival and relay registrations (09, 17) get a new row naming G (every other column copied); every active dataset it set is re-inserted with setter G (and added_by G when it was the setter) and the old row deactivated (10). A DFS file row (setter = recipient, property starting dfs:) moves whole: setter and recipient both G, and added_by = the joining address, its original owner; afterwards only the group's controller and that original owner may change or delete the file (10 §11); a member's file created after joining records its creator the same way. Leaving the group takes nothing back, the right to the file included.

How to compute it. As stated. Rows are found by the joining address's typed bytes and, for a type-0 address, also by its last 32 bytes (no owner column holds that form on a chain where every account is typed, so the second form matches nothing there).

Rule activation. account_groups, active from height 0 on every chain.

Rejections and errors. The blockers of §7 refuse the link before any move.

Vector. computed.

  • Input: M joins G holding 100,000,000 ZBC, 5 units of token 1, an open swap offer and a node registration it owns.
  • Expected output: on M event 48 −100,000,000, on G event 49 +100,000,000; G's token-1 balance +5, M's 0; the offer's and the registration's new rows name G as maker / owner; M's account row empty with its nonce kept; the registration's rewards (21) land on G from then on.

Test cases · §6

1 case · 1 valid

M joins with 1 ZBC and 5 units of token 118-6-movesvalid

Loading the test widget…

Defects to match. (1) Pending escrows, active liquid payments and app seats naming the address do not move; they keep working through the same-account test and the player match (12, 08, 16), and what they pay after the address leaves is the address's own. (2) The move counts at most ACCOUNT_GROUP_MAX_MOVED_ITEMS 1,000 items (§7).

7. The join blockers

Purpose. What refuses a link, each naming a hazard.

Inputs. The address A, the group (or nothing, for a founder), the co-joiner (the founder, when founding).

Output and effect. The first of these that holds is the refusal text: A is a group address ("the address is a group account; a group cannot join another group"); A is an active member ("… already a member of a group; it must leave that group first"); A's type cannot sign; A is a system pool (ZBCLONGV, ZBCSTORE, the lottery carry ZBCCARRY; "a system pool cannot join a group"); A has a split policy; A is the release authority or its pending successor; A's key (ZBC-typed) is an active node, gateway, relay or archival key; A and the group (its address, its members, or the founder) would both own a node registration; A and the group hold seats in the same Open or Active app; A owns more than 1,000 items to move (the sum over the thirteen categories of §6); the group already set the same dataset property on the same recipient as A did; for a DFS file row of A, the group already has an active file at the same path (the whole-file move would overwrite it).

How to compute it. As stated, in that order.

Rule activation. None.

Rejections and errors. "LinkAccount: the controller cannot found a group: <text>", "LinkAccount: the member cannot join: <text>"; the file blocker's text is "the group already has a file at <path>; delete one of the two files first" (path = the property after dfs:).

Vector. computed.

  • Input: the TestNet genesis gateway owner 00000000ED52418C88A6DF31FC4DAE2523C1673CB2E286710B0D1C99EF1BB27501014451 founds a group. Expected: allowed by this list (it owns a gateway, which moves to the group).
  • Input: the account 00000000 ‖ 93CBCBC3E3D3B7459B881EAFDBF0EC462824599DE215FE48D181805441BF908A (type 0 over that gateway's key) as a member. Expected: refused, "LinkAccount: the member cannot join: …" naming the active gateway key.
  • Input: the longevity pool 000000005A42434C4F4E4756…00 as a member. Expected: "LinkAccount: the member cannot join: a system pool cannot join a group" (it cannot sign a consent anyway).

Test cases · §7

3 cases · 1 valid · 2 invalid

The genesis gateway's owner founds a group18-7-gateway-ownervalid

Loading the test widget…

The account over the gateway's key as a member18-7-gateway-keyinvalid

Loading the test widget…

The longevity pool as a member18-7-poolinvalid

Loading the test widget…

Defects to match. The apps pool ZBCAPPS (16) is not in this list (it is rent-exempt but not a "system pool" here) and could be named as a member if someone could sign for it (nobody can).

8. A member's transaction: the gate and the limit

Purpose. What a member may send as the group, and how a spending limit is enforced.

Inputs. The signed transaction; the member row; the block height.

Output and effect. For a sender that is an active member (one gate, identical at admission, assembly and execution): the controller may send anything, unlimited. Otherwise: UnlinkAccount of itself is allowed; the controller-only types (LinkAccount, SetMemberPermissions, TransferGroupControl, SetSplitPolicy, SetTransactPolicy) are denied; a member without bit 0 is denied; bit 0 with spend_limit 0 is allowed without measure; with a limit: a transaction that may move tokens (TransferToken, TransferTokenBatch (14 §4a), BurnToken, a token LiquidPayment or ScheduledTransfer, a swap giving a token or accepting one wanting a token, an order whose hold is a token, an app staked in a token) is denied unless bit 1; the worst-case ZBC outflow (fee + the type's largest possible take, below, saturating at 2⁶³−1) added to the window's spent (0 when the window has closed) must not exceed spend_limit. The largest take per type (ZBC only; every other type 0; QueueAttendance counts nothing, not even its fee):

Type Counted
SendZBC, AddPrepaidStorage the i64 at body offset 0
SendZBCBatch every payment's amount (08)
IssueToken the backing (offset 10)
CreateTrigger, FundLongevity, FinanceToken the i64 at offset 8
StoreFile the rent deposit (offset 44)
FundStoredFile the top-up (offset 32)
RegisterGateway the voted gateway_registration_cost held to its bounds (17 §7)
CreateMarket market_creation_cost held to its bounds (15)
MintToken ceil(amount × backing / supply) + (that ≫ 40) + 2, when backing and supply > 0
NodeRegistration, NodeRegistrationUpdate the body's locked balance
LiquidPayment the amount, for ZBC
ScheduledTransfer per-fire amount × remaining fires, for a pre-locked ZBC schedule
CreateSwapOffer the give, when the give token is 0
AcceptSwapOffer the offer's want, when its want token is 0
PlaceOrder a sell on a ZBC base: the amount; a buy on a ZBC quote: floor(amount × price / 10⁸); plus, with CancelOrder, the market-rent share ceil(fee × 2,000 / 10,000) (15)
CreateApp, JoinApp the stake, for a ZBC stake

Every type also adds the explicit token survival payment (13 §10), the header survival, an escrow's commission and rent, and a pull schedule's deferred draws. A denial makes the block invalid (rule group_spend_invalid_block; the executor returns "Account group: <reason>"). An allowed transaction runs with the group as sender (the management types keep the signer); a measured one runs inside a savepoint (a state snapshot that can be undone): afterwards outflow = the decrease of the group's balance (0 when it rose) + the deferred draws; if it exceeds what was left, or (without bit 1) any token balance of the group fell, the savepoint is undone and the block is invalid; else the member's window is updated (window_start = height and window_spent = 0 when height ≥ window_start + period_blocks, then window_spent += outflow). Block assembly skips a member's transaction whose worst case, with those already selected, passes the window, and defers transactions of a group touched by a management transaction in the same block (local policy).

How to compute it. As stated.

Rule activation. group_spend_invalid_block, schedule_fire_member_gate, market_rent, active from height 0 on every chain. The measured (savepoint) path counts the group's actual balance decrease, which already includes any market-rent contribution the order paid.

Under the one-transaction-per-account rule (19 §2) the account is the signing address, so each group member has its own slot and the controller another; a group's members can each land one transaction in the same block.

Rejections and errors. "Account group: only the group's controller can remove another member", "… only the group's controller can send this transaction type for the group", "… this address is a receive-only member of its group; the controller has not enabled it to spend", "… a member with a spending limit may move the group's tokens only with the controller's token permission", "… the member's spending limit would be exceeded (S of L used this period, this transaction can take up to X)", and at execution "Account group: the member's spending limit would be exceeded by what the transaction took". A MultiSignature whose inner transaction a multisig member may not send is refused at admission and fails the block that completes it (12).

Vector. computed.

  • Input: a member with flags 1, limit 50,000,000, period 1,000, nothing spent, sends a SendZBC of 48,000,000 with declared fee 2,550,000.
  • Expected output: refused at admission "Account group: the member's spending limit would be exceeded (0 of 50000000 used this period, this transaction can take up to 50550000)"; a block carrying it is invalid.
  • Input: the same member sends 47,000,000 with fee 2,550,000 where the floor is 2,500,000. Expected: admitted (worst case 49,550,000); executed as the group: the group −49,550,000 then +50,000 overpay (event 22), so outflow = 49,500,000 and window_spent 49,500,000.
  • Invalid input: a receive-only member (flags 0) sending anything but its own UnlinkAccount → "Account group: this address is a receive-only member of its group; the controller has not enabled it to spend".

Test cases · §8

4 cases · 2 valid · 2 invalid

A member sends 0.48 ZBC with a fee of 0.025518-8-over-limitinvalid

Loading the test widget…

A member sends 0.47 ZBC with a fee of 0.025518-8-withinvalid

Loading the test widget…

A receive-only member sends anything18-8-receive-onlyinvalid

Loading the test widget…

After the measured spend: the group's net decrease is counted18-8-windowvalid

Loading the test widget…

Defects to match. (1) The window counts the net decrease of the group's balance, so an incoming credit in the same transaction reduces what is counted. (2) The receive-only default means a freshly linked member can do nothing but leave until the controller acts.

9. Rent, dissolution and the views

Purpose. What a group pays and what ends it.

Inputs. The group's account row; account_rent_period_cost, dataset_storage_cost_per_mib, storage_oracle_multiplier_ppm.

Output and effect. The group pays account rent as any account (13 §9) with cost = the period cost + StorageFee(weight, cost_per_mib, ppm) (10 §12, each stage rounded up); the rent is credited to the longevity pool, paid from the group's prepaid storage first, and the period cost is capped at 10 ZBC by governance_window. weight = 96 + len(controller) + Σ over active members (len(address) + 40); members pay no rent and arm no clock. A group whose balance and prepaid storage together cannot cover it is pruned: the row tombstoned (13 §9), status 0, every member row inactive and every member address reset fresh; the group's balance and prepaid storage go to the longevity pool (event 50; ZBC is never burned); its members lose nothing of their own. Views: /groups/<a> and /accounts/<a>/group (address, role none / member / controller / group, group_address, group_address_zbc, controller, status, link_seq, created_height, max_members, balance, spendable_balance, rent_due_height, weight_bytes, rent_per_period, members[] with address, address_zbc, role, linked_height, permissions {controller, can_spend, may_move_tokens, flags, spend_limit, period_blocks, window_start, spent_in_window}); /accounts/<member> answers with the group's balance and a group block.

How to compute it. As stated; StorageFee(bytes, cost_per_mib, ppm) = ceil(ceil(bytes × cost_per_mib / 1,048,576) × ppm / 1,000,000) in 128-bit, 0 for 0 bytes.

Rule activation. None.

Rejections and errors. None.

Vector. computed (TestNet: cost 1,000,000, dataset_storage_cost_per_mib 5,000,000, ppm 1,000,000).

  • Input: a group with a type-0 controller and one other type-0 member. Expected: weight 96 + 36 + 2 × 76 = 284; rent 1,000,000 + ceil(284 × 5,000,000 / 1,048,576) = 1,000,000 + ceil(1,354.2) = 1,001,355 per period (/groups/<G> weight_bytes 284, rent_per_period 1,001,355).
  • Input: the controller alone (weight 96 + 36 + 76 = 208). Expected: 1,000,000 + ceil(991.8) = 1,000,992.
  • Input: 100 type-0 addresses, the controller included. Expected: weight 96 + 36 + 100 × 76 = 7,732 bytes, ceil(7,732 × 5,000,000 / 1,048,576) = ceil(36,869.05) = 36,870 per period on top of the cost.
  • Input: a group due with balance 900,000, prepaid 0. Expected: pruned: the group row tombstoned and status 0, every member row inactive and every member address fresh, the pool +900,000 (event 50).

Test cases · §9

4 cases · 4 valid

A controller and one member18-9-twovalid

Loading the test widget…

The controller alone18-9-onevalid

Loading the test widget…

One hundred addresses, the controller included18-9-hundredvalid

Loading the test widget…

A group due its rent of 1,001,355 holding 900,000 is pruned18-9-prunedvalid

Loading the test widget…

Defects to match. The weight counts the controller's own address twice (once as controller, once as a member), as the formula says.

10. Ledger rows and the consensus/local split

Event Row Written by
1 payer −fee the four types (the founder's own row for a founding link; otherwise the group)
22 group +overpay the four types' own settlement (never the generic one)
48 / 49 address −balance / group +balance LinkAccount's moves (transaction_id = the link; the timestamp is the transaction's, never the node clock)
50 pool +balance + prepaid a group pruned for rent (13 §9)

Consensus: both tables, the address derivation, the digest and consent rules, every check above, the moves, the gate and the measured limit, the rent weight, the dissolution. Local: the ledger rows, the assembly deferral, the views.

A question about this chapter, or a statement that does not match the network? Discuss on zoobc.pro.