Skip to main content
This feature was introduced with version 0.13.1 of the Registry App; version 0.7.1 of the utility-registry-v0 (the block list check field), extended with sharding and UI support in version 0.14.0 of the Registry App; version 0.8.0 of utility-registry-v0.An instrument for which the blocklist check is enabled is not compatible with Daml models introduced in previous releases.

​
Overview

A blocklist is managed at the instrument admin (i.e. registrar) level, and applies to all instruments managed by that party for which the blocklist check is enabled. Once enabled on an instrument, every sender and receiver (or holder, for burns) involved in a transfer, mint, burn, or allocation of that instrument — across both Token Standard V1 and V2 flows — must not appear in the registrar’s blocklist, or the transaction is rejected. On-ledger, the blocklist is a set of StoredBlockListPartyShas contracts (“shards”), signed by the registrar and observed by the operator, that store the SHA-256 hashes of blocklisted parties, sharded by hash prefix (see Cost considerations). The steps below can be performed either from the Registry dApp UI, or directly against the ledger/JSON API by exercising the underlying choices — both paths are equivalent.
You can jump straight to a step: 1. Instantiate · 2. Enable on an instrument · 3. Add parties · 4. Remove parties · 5. View.

​
Step-by-step setup guide

1

Instantiate the blocklist

When a registrar onboards (accepts a RegistrarServiceRequest) from version 0.14.0 of the Registry App onwards, 16 shards are created automatically for it, one for each hexadecimal prefix character (0-f), each with a maximum shard size of 16 entries — no further action is needed.Registrars onboarded before this feature was available (or whose shards are otherwise missing) must instantiate the blocklist once before it can be used.
Navigate to Blocklist in the left navigation sidebar and click Create blocklist. The button is disabled once shards already exist, so it is safe to attempt this step even if you are unsure whether the blocklist was already created.
Do this before enabling blocklist verification on any instrument — otherwise all transfers, mints, burns, and allocations for that instrument will fail, since no StoredBlockListPartyShas shard will be resolvable for the disclosed choice context.
2

Enable blocklist verification on an instrument

Blocklist verification is configured per instrument, via the checkBlockList field of the instrument’s InstrumentConfiguration contract.
Tick Use block list when creating the instrument from Configuration, or open an existing instrument and enable it via the modify dialog.
Enabling the blocklist check on an instrument makes it incompatible with Daml models introduced before release 0.13 (the checkBlockList field cannot be dropped when downgrading to a package version that predates it).
3

Add parties to the blocklist

From the Blocklist page, click Add party to blocklist, enter the party id(s), and confirm.
Once added, the party is blocked for every instrument of that registrar with blocklist verification enabled.
4

Remove parties from the blocklist

From the Blocklist page, locate the party in the table and click Remove, then confirm.
5

View the current blocklist

The Blocklist page lists all currently blocked parties. A “view raw” option is also available for inspecting the underlying StoredBlockListPartyShas shards and their stored SHA-256 hashes directly, rather than the resolved party list.

​
How the check runs at transaction time

When blocklist verification is enabled on an instrument, every transfer, mint, burn, or allocation resolves and discloses only the relevant shard(s) via the choice context, then checks the sender/receiver against them:

​
Cost considerations

Using the blocklist feature requires additional contracts to be disclosed as part of the ChoiceContext for transfer, minting, burning, and allocation transactions. The blocklist is sharded across different party prefixes, so that the cost of these transactions is bounded, rather than linearly increasing with the number of parties in the blocklist. Concretely:
  • Parties are identified in the blocklist by the SHA-256 hash of their party id, not the raw party id.
  • The blocklist starts as 16 shards, one per single hex-character prefix of that hash.
  • Each shard independently splits into 16 children (extending its prefix by one more hex character) once it would exceed its configured maxBlockListShardSize, so shard sizes stay bounded regardless of how many parties are blocklisted overall.
  • At transaction time, only the shard(s) whose prefixes match the sender’s and receiver’s (or holder’s) party hash need to be resolved and disclosed via the choice context — not the entire blocklist — keeping the disclosure size, and therefore the transaction cost, roughly constant as the blocklist grows.