Skip to main content

Balance, voting, hold and supply features

Reference for the historical balances, voting power, hold and supply delegate token features: what each records or restricts and who operates it.

Four token features cover balances over time and who may move or create units. Historical balances records balances so any past time can be read, and voting power turns balances into vote weight. Hold reserves units in a holder's wallet without moving them, and supply delegate lets a registered wallet or add-on mint and burn. This page states what each feature does, its parameters, and who operates it after issuance, with a worked example.

A token feature is a module attached to one token. An account with the token's governance role attaches, detaches and configures it after issuance where the feature allows it, and each entry names any other role an action needs. The DALP Library is the catalogue of instrument templates that ship with the platform, and each entry says which of them include the feature.

Historical balances

Records every account's balance and the total supply after each mint, burn, or transfer, so any past time can be queried. The token calls the feature once for each operation with the legs that executed. The feature sums each account's net change and writes one checkpoint per touched account, plus one for total supply when it changed. Checkpoints are keyed by timestamp, and several writes in one block keep the last. balanceOfAt and totalSupplyAt return the latest checkpoint at or before the time you ask for, and a future time is rejected. Dividend yield, interest yield, and the distribution waterfall read it for record-date balances, and fixed treasury yield needs it too, as Income features describes. Choose it on any token that pays dividends or interest. The DALP Library includes it on 35 of its 36 system templates, all except Custody receipt. Ledger Data explains why a point-in-time record matters.

The feature has no parameters and no role after issuance. It cannot be detached while fixed treasury yield, dividend yield, interest yield, or the distribution waterfall is attached. The Console's attach list does not offer it. It arrives through a template or through the Platform API's attach route.

The feature records the time it started. A token has 1,000 units on day 0, and the feature starts on day 10. The standard totalSupplyAt query for day 5 returns 0, because no checkpoint exists at or before day 5. The strict variant rejects the same query with QueryBeforeEnabled. A query for day 12 with no activity since returns 1,000.

While the feature is detached it records nothing, so a lookup for that period returns the last checkpoint written before the detach. Remove dependent features before detaching historical balances.

Voting power

Turns balances into voting units with their own checkpoints. A holder has one voting unit per token held. Units count as votes only for the address the holder delegates to, so a holder who has not delegated has no votes. The Console action “Activate voting power” delegates to the holder's own wallet. On every mint, burn, and transfer, the feature moves units between delegates and writes checkpoints, so getPastVotes and getPastTotalSupply answer for a past time. Delegation moves vote weight and leaves token balances unchanged. The token's governance addon reads the feature as its source of vote weight. The DALP Library includes it on eight templates: Commercial Real Estate, Common Equity, Convertible Target Equity, Economic Class Share, Employee Equity Award, Mutual Fund, Private Equity Fund, and Tokenised Art.

The feature has no parameters. After issuance, a holder delegates. A holder delegates through the delegation route, which needs an activated identity registration for the delegating wallet. The Platform API has no route that relays a delegation signed off platform. Governance attaches and detaches the feature, and the Governance wizard offers an inline attach when the token lacks it. A detach is blocked while the token's governor has pending, active, or queued proposals.

Alice holds 600 tokens and Bob holds 400. Alice has activated her voting power, and Bob has not. A vote with record date T reads 600 votes for Alice and 0 for Bob. The total supply at T is 1,000, so the delegated weight is 600 of 1,000. If Bob delegates after T, his weight counts only for votes with a later record date. See Governance for the screens.

Hold

Lets a reserver, an account or add-on authorised to hold units, commit units in the holder's wallet without moving them. The units stay where they are, but the holder can no longer spend them: a transfer or burn above the available balance is rejected with AmountExceedsAvailable. The available balance is the balance, less the units the custodian froze, less the units held. A wallet the custodian froze in full has no available balance. Releasing a hold moves no units, and the feature records a release event. A reserver places a hold on any holder's units and can deliver the held units to a recipient, without the holder's signature. The delivery runs the token's full compliance path. Each reserver touches only its own reservations. A hold can have a lifetime in seconds or never expire, and an expired hold stops counting at once. Choose it when an add-on, such as the custody gateway, must commit units inside the holder's own wallet. The DALP Library includes it on 34 templates, all except Controlling Class Share and Economic Class Share. It comes first in every one except Share-Class Mirror, which lists historical balances first.

The feature has no attach parameters. It starts with an empty reserver list. Governance authorises outside reservers, and a feature attached to the same token enrols itself, with no expiry, the first time it places a hold. Each enrolment takes one of the 32 slots, and a detached feature keeps its slot until governance removes it. Authorise a reserver only for a system you trust, such as the custody gateway.

After issuance, an account with the governance role authorises and removes reservers, at most 32 at a time. The Console lists the reservers and removes them, and adding a reserver is a Platform API action that accepts a lifetime. Removing a reserver makes all its reservations stop counting at once. Anyone can clear a reservation that no longer counts, because it expired, its reserver was removed, or the feature that placed it was detached, and the Features tab lists these inactive reservations with a “Clear” action. A forced custody update, such as a custodian forced transfer, passes the check by design, and mints never touch held units.

A holder has 1,000 units. The custodian froze 100, and a reserver holds 300. The available balance is 600, so a transfer of 700 reverts with AmountExceedsAvailable, and so does a new reservation of 700. A custodian forced transfer of 700 succeeds and can leave the holder below the held total, and the available balance then reads 0.

The feature belongs first in the token's list, so a fee or rewrite feature cannot consume units that the hold already committed. The DALP Library puts it first on every template except Share-Class Mirror, and a feature attached later goes to the end of the list. The Console attaches it from the “Attach a feature” list on the token's Features tab. It runs on EVM only.

Supply delegate

Lets a registered wallet or add-on mint and burn a token's units without holding the supply management role. The governance role decides who may mint, who may burn, and how many units a minter may have outstanding. A delegate is a wallet, or a contract that vouches for other callers, such as a system add-on factory that vouches for the add-ons it deployed. A vouching delegate does not mint or burn itself. Each caller it vouches for acts as the delegate. The platform rejects a vouching delegate that is not a contract answering which callers it vouches for. Each delegate may mint, burn, or both, and a delegate with neither is rejected. Choose it when a system, such as a custody gateway or the bank rail, must create and retire units in step with deposits and payments, and you do not want to hand that system the supply management role.

The feature has no attach parameters. It starts with no delegates, so it mints and burns nothing until governance adds one. A token holds at most 32 delegates. Adding a delegate that is already registered is rejected. To change its permissions, remove it and add it again.

A mint runs the token's full compliance path, so a receiver that the token's compliance rules reject is rejected. A burn takes units only from the caller's own balance, so a delegate cannot burn another holder's units, and units that a hold feature reserves stay out of reach. Each mint and burn has a 32-byte reference that the caller picks, or zero for none. A custody gateway passes its deposit or request identifier, and the bank rail passes a hash of its bank transaction identifier, so no bank data goes on the chain. The platform does not check that a reference is unique.

A minting delegate can have a cap. The cap bounds the delegate's outstanding units, which are its mints minus its own burns, never below zero. A burn frees room under the cap again, but only for units that leave the total supply: when a transaction fee feature turns part of a burn into a fee payment, that part frees nothing. A vouching delegate has one count shared by every caller it vouches for. With no cap, the delegate can mint any amount, and governance can register a minter without one, so set a cap for every delegate you add. A mint past the cap is rejected with an error that names the cap and the outstanding count. A delegate with a cap of 1,000,000 units that has minted 600,000 and burned 200,000 has 400,000 outstanding and may mint 600,000 more.

After issuance, an account with the governance role attaches and detaches the feature. The Console attaches it from the “Attach a feature” list on the token's Features tab, and its section there shows a short description. The Platform API adds and removes delegates, with the governance role and a wallet verification. Removing a delegate stops its next mint or burn at once, but its outstanding count stays, because the units it minted are still in circulation. The feature cannot sit beside the booked movements feature, which keeps register lines and which this catalogue does not cover: a template or an attach that combines them is rejected. The DALP Library includes it on one template, Custody receipt, which pairs it with hold. It runs on EVM only. Custody receipt explains the gateway that uses it, and Bank rail covers the other.

Was this page helpful?