Whitelists
How to create, read, and maintain Whitelists on Ledger Enterprise, the two kinds of Whitelist, and how to handle an urgent counterparty change.
Role: Master Administrators write. Other Administrators and Operators read.
A Whitelist is a named list of permitted destination addresses. Policy Rules reference Whitelists, and Approvers see the resolved destination on their device at signing time.
There are two types of Whitelist:
A Transaction Whitelist holds destinations for Send Rules.
A Smart Contract Whitelist holds contract addresses for Contract Interaction Rules.
The Whitelist form creates Transaction Whitelists.
A Send Rule offers only Transaction Whitelists. A Contract Interaction Rule offers only Smart Contract Whitelists.
Smart Contract Whitelists
Only a Master Administrator creates a Whitelist, of either type. The Whitelist form has no type choice, so a Master Administrator creates a Smart Contract Whitelist outside the interface. It is a Create whitelist Request with the type SMART_CONTRACT. An API Administrator cannot create a Whitelist of either type.
The Master Administrator quorum approves it on their Ledger devices, as for a Transaction Whitelist. Each entry holds a contract address. A Contract Interaction Rule matches a call when the called contract is in one of its Whitelists.
The Whitelists list
Whitelists are listed most recently updated first. Each row carries the name, a truncated description, the number of Entries, the Networks represented, the Status (Active or Inactive) and the Last update date. Sort by name, entries, status, or last update.
The search box, Search by name, address, or ID, matches Whitelist names, addresses and address names. It also matches an exact Whitelist ID. It searches from 3 characters. Paste a destination address to see which Whitelists contain it. That is the fastest answer to "is this address allowed anywhere?". To find the entry, open the Whitelist and search its entries.
The Networks filter offers the networks enabled for your Workspace. A Whitelist matches when it holds an address on any selected network. The Activation Status filter shows Active or Inactive Whitelists.
Each row has a menu with Copy link to whitelist. It copies a link to the Whitelist's page.
Creating a Whitelist
The create flow collects a name and an optional description, then the entries. The name has up to 45 characters, ASCII only, and is unique in the Workspace. A Whitelist needs at least one address. Each entry has:
Address name
Required, up to 50 characters. This is what Approvers and auditors read
Network
Required. Each entry binds to one network, from the networks enabled for your Workspace. There are no multi-network entries
Address
Required, up to 200 characters. Validated against the network
Destination tag
XRP only. Optional
Review creates the Whitelist Request and asks you to approve it on your Ledger device. When the Master Administrator quorum approves it, the Whitelist is active. A Send Rule then offers it in single-asset Policies on a network where it holds an address, and in any-asset Policies. A closed form is not saved as a draft.
An entry covers every asset on its network. A transfer from a token Account to the entry's address matches the entry, like a transfer of the network's native asset. A token needs no entry of its own.
Note: There is no maximum number of addresses in a Whitelist.
Important: The address name is the human-readable half of the entry, and often the only part an Approver can meaningfully check against their own records. "OTC partner, BTC cold" is useful. "Address 3" is not.
Editing a Whitelist
The name and the entries are editable, with the same validation as at creation. The description is set at creation and cannot be changed. Review creates an edit Request. While it is pending, the Whitelist is locked, in the interface and through the API alike.
When the addresses added and removed in one edit total 90 or more, the form shows Large number of edits. It recommends smaller batches, to make verification on the Ledger device easier. The banner does not block Review. A changed entry counts as two changes: one removal and one addition.
While the edit Request is pending, it shows the addresses added and removed, and any name change. In any other state, the Request shows the full name and address list.
Renaming or editing a Whitelist does not break the Policies that use it. Policies point at a Whitelist by identity, not by name, so a rename is safe. And when you change the addresses, every Policy using that Whitelist picks up the change as soon as the edit is approved.
Reading a Whitelist
The detail shows its description, the Created and Last updated dates, the Networks, and:
The entries, each with its address name, network, address and a copy action, and destination tag where relevant. Search entries by name or address, from 3 characters. Filter them by network.
Linked policies, every Policy referencing it. Administrators only, since Operators may not have visibility on all Policies.
History, the executed creation and edit Requests on it, each with its review timeline and a link to the Request. Pending and rejected Requests do not appear here.
When a counterparty changes urgently
Removing a compromised or rotated address goes through the full approval cycle. There is no emergency bypass, by design: an attacker who could bypass approval to add an address would own your outbound flow.
What you can do to make it fast:
Sort by last update so the Whitelist you are working on stays at the top.
Write the note on the Request so Approvers understand the urgency without a phone call.
Keep Whitelists narrow. A Whitelist per counterparty is quicker and safer to change than one large Whitelist shared across many Policies, where a single edit touches everything.
Know in advance who your Approvers are and when they are reachable. The constraint in a fire-drill is almost never the software.
Note: A whitelisted destination states that your governance permits it, not that it is safe. Whitelisting governs where funds may go; it does not screen for risk.
What Whitelists do not do yet
No archive or delete. Obsolete Whitelists remain in every list and picker.
No bulk import. Entries are added in the form.
No distinction on the Approver's device between a plain address and a smart contract. If your Policies allow contract destinations, treat the Whitelist as one control among several rather than the whole story.
Related
Last updated