On this page
- §0 The area in one paragraph
- 1. The group address, the tables and the resolution rule
- 2. The bodies and the consent proof
- 3. LinkAccount (55)
- 4. UnlinkAccount (56)
- 5. SetMemberPermissions (57) and TransferGroupControl (58)
- 6. What joining moves
- 7. The join blockers
- 8. A member's transaction: the gate and the limit
- 9. Rent, dissolution and the views
- 10. Ledger rows and the consensus/local split
18 — Account groups: LinkAccount, UnlinkAccount, SetMemberPermissions, TransferGroupControl
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_members100 in both live genesis files and the mainnet template): for the TestNet treasuryGET /api/v1/accounts/00000000120ee4ca9d258d75656901ec4837373e07763369ad75ed8d63fa31c7e0b7e807/groupanswers{"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 AB
Loading the test widget…
The group view of the TestNet treasury while it is in no group
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:
- 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. - Kind 0: the consenting address's signature over the 32-byte digest, verified by its address type
(
02). - 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(MetaMaskpersonal_sign), or Tron-typed (type 15), whose signature is over"\x19TRON Signed Message:\n32" ‖ digest(TronLink: TronWeb'ssignMessageV2, prefix ‖ decimal length ‖ message, and its oldersignString, the fixed…\n32prefix ‖ message, give these same bytes for a 32-byte digest). Either is verified as an Ethereum signature: the key is recovered fromkeccak256(prefix ‖ digest)and its Keccak address must be the address's 20 bytes. - Kind 1: the consenting address must be a multisig account; the participants (no duplicates,
1…255, none of them a full-key form,
01) withminimum_signatures(1…n) andnoncederiveH(12§9), and the typed account00000000 ‖ Hmust be the consenting address (the form the chain stores; the bareHis 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 leastminimum_signaturesmust 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 digest999E96F16DB8BF3BE83B59FCE3DFC56F3CC7FA0397DC80BCBAA502F24FF66120. - Input: the same with tag
ZBC-GROUP-CONTROL, link_seq 3. Expected: control digest7B3637C306EFF8F6FFEFC9BC316263C292A2FBF6F4A5E01C6DBA57B70278334D. - Input: the vectors' identity
Gof02§1 (E003E4E3557EF19F0519BD345009DEA7FB43B3445EAA043920C5DC23B3302871, an example value: a chain uses its own genesis hash), controller00000000120EE4CA9D258D75656901EC4837373E07763369AD75ED8D63FA31C7E0B7E807, member00000000B6675786BEDF28B3E7DCD8BAC9BF99758B3A64604570BFFD12FD10CBF20B39EA, valid_until 20,000, link_seq 0. Expected: link digestD503C25A8D7A14E9CA38DCAD639CC4E0494A0092372FCB405051444EC490D3E9; the LinkAccount body is01 ‖ 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 key71a02da87982b42c8ad61d5e3c30dfc20cd369b75621fc709734a44c355cfe50(= SHA3-256("ZooBC spec vector tron consent key"), a test key), public keyC74549AF6B5471375C00F48BF2871A78117B781B9D0154FBFC54230C7C8D1A6BE2688171E8DABF5E0643891613BF0C84BA94F8CFA1FD02C170D27DC4DF63BCB3, member T =0F000000 ‖ 9C1A9D01F45581F7CB95BF81AA1A95997700A10D(type 15, the key's Keccak address), valid_until 1,000, link_seq 0. Expected: link digest593B9F220ABADF8A96D5733A1F36C79A8077FA6F183622A25AB3B94D977AB78F; the signed payload (56 bytes)1954524F4E205369676E6564204D6573736167653A0A3332‖ digest, whose Keccak-256 is1E17891291C4AC4417F478FA95ECDB7B25EDCBCF9E51376320094BB0FB9C3B16; 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 =
0000000041F9A78A8E744E097002DE7303FB0648F44ED0D5D3EA195ACCD8BFA7897E61F1and P2 =000000007D045551B600B10C872D2E53507911DC52CFE11AD3966B60ECC87C875E3BCA4E(the Ed25519 keys of the seeds SHA3-256("ZooBC spec vector multisig participant 1") and "… 2"),minimum_signatures1, nonce 7, so the member is00000000C5AC58F44D7B642638605B72BCCC34739F5FD4B4E5D69563F071B8F1FB07DE90(00000000 ‖ H,12§9); valid_until 1,000, link_seq 0. Expected: link digest26A7907DA15846173799482F599DA3FF04982968E4FACD694859B54CD42A7846; P1's signature over itAA9759CC18BFFDDB061DF8EECD3D6AD1BEA0DBB039BC7C10BF74A44AB954FBA3B891B946ABFF433A60F64C4113922CB367BA75A1E37D2B34064C26B204393602; 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 byte1Breplaced by00(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
A link digest for an Ethereum member
Loading the test widget…
The same with the control tag and link_seq 3
Loading the test widget…
The link digest of two ZooBC accounts under the vectors' identity G
Loading the test widget…
The link digest and the signed payload of a Tron member's kind-2 consent
Loading the test widget…
A LinkAccount whose Tron member consents with TronLink's message signature (102 bytes)
Loading the test widget…
The same body with the signature's last byte 1B replaced by 00
Loading the test widget…
The Tron member written as its full-key form
Loading the test widget…
The link digest of the multisig member
Loading the test widget…
A LinkAccount whose 1-of-2 multisig member consents through one participant (202 bytes)
Loading the test widget…
The same body with nonce 8
Loading the test widget…
A LinkAccount body consented by the member's Ed25519 key (here the key of seed 32 bytes of 11)
Loading the test widget…
A SetMemberPermissions body: spend, 0.5 ZBC per 1,000 blocks
Loading the test widget…
The token permission without the spend permission
Loading the test widget…
A member field holding a bare 32-byte key
Loading the test widget…
A LinkAccount body with one trailing byte
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:
- The fee is taken from the balance holder of S (S itself for a founder; row event 1); an unaffordable fee → nothing taken.
- The checks of §2 and the state checks: a founder (S in no group) needs
account_group_max_members≥ 2,link_seq0 and no blocker of §7 on itself; a controller needslink_seq= the group's counter and fewer thanaccount_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. - Founding: the group row (controller S,
link_seq0, status 1,created_height) is written, S's assets move into the group (§6), S becomes an active member row (flags 0,linked_height). - M's assets move (§6); M becomes an active member (flags 0, no limit,
linked_height= height). - The group's
link_seq+= 1 (a founding link therefore ends at 1). - The consent digest is marked spent (
spent_foreign_message,02§9), so it never verifies again. - 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_seq1, status 1,created_heighth); member rows for C and M (flags 0,linked_heighth); 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 moves
Loading the test widget…
The same link sent again
Loading the test widget…
The link at height 20,001
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 removes M
Loading the test widget…
The controller names itself
Loading the test widget…
A third member removes M
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_limit50,000,000,period_blocks1,000, window unchanged (window_start0,window_spent0 for a new member). - Input: TransferGroupControl (type 58) to M with
link_seq1 and M's consent over the control digest. Expected: controller M,link_seq2; 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 blocks
Loading the test widget…
The controller hands control to M
Loading the test widget…
M sends the permissions body
Loading the test widget…
M sends a permissions body naming X
Loading the test widget…
A SetMemberPermissions body naming the Tron member in its full-key form
Loading the test widget…
M, not the controller, hands control to X
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 1
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
00000000ED52418C88A6DF31FC4DAE2523C1673CB2E286710B0D1C99EF1BB27501014451founds 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…00as 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 group
Loading the test widget…
The account over the gateway's key as a member
Loading the test widget…
The longevity pool as a member
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 andwindow_spent49,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.0255
Loading the test widget…
A member sends 0.47 ZBC with a fee of 0.0255
Loading the test widget…
A receive-only member sends anything
Loading the test widget…
After the measured spend: the group's net decrease is counted
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_bytes284,rent_per_period1,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 member
Loading the test widget…
The controller alone
Loading the test widget…
One hundred addresses, the controller included
Loading the test widget…
A group due its rent of 1,001,355 holding 900,000 is pruned
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.