Policies
How to create, read, edit, and reuse Policies on Ledger Enterprise, and how to judge the blast radius of a change.
Role: Master Administrators write. Other Administrators and Operators read.
A Policy is a reusable, named Rule set. One Policy can govern many Accounts, so editing it changes the governance of every adopting Account at once. That is its value and its risk.
The Policies list
Policies are listed most recently updated first. Each row shows the name, with the asset or Any asset beneath it. The Rules column shows one icon for each operation type that has Rules. The Last update column shows the date of the last change.
Sort by name or last update. Search by name or by exact Policy ID. Filter by Asset or by Policy type. Your filters are kept in the page address, so a filtered view can be shared or kept for audit.
Only shared Policies appear here. An Account using its own Rules is backed by an automatically named private Policy, deliberately hidden.
Single-asset or any-asset
The first decision when you create a Policy is whether it applies to one asset or any asset. The Policy type field defaults to Single asset. The other option is Any asset.
Single asset
Available
Accounts on the network of that asset
Any asset
Not available
Any Account
Thresholds only mean something against a known unit, so an any-asset Policy cannot carry them and the combination is rejected.
Important: This choice, and the asset itself, is locked once the Policy exists. You cannot convert a single-asset Policy to any-asset later. If you need the other shape, use the Policy as a template and create a new one.
An any-asset Policy applies one approval chain across assets, for instance to one counterparty's whole treasury. A single-asset Policy supports tiered amount thresholds.
Creating a Policy
The create flow opens on its own page. It asks for:
A name, up to 45 characters, unique in the Workspace
An optional description
The Policy type, Single asset or Any asset, and the Crypto asset for a single-asset Policy
One or more Rules
Each Rule collects:
Operation type
Send, Receive, Stake, and the other governed operations
Request initiator
The Operators or the group that can create the Request. Creating the Request counts as the first approval. This step has no quorum
Approval steps
One or more ordered steps. Each step holds a list of Operators or one group, with a quorum
Whitelists
Send Rules take Transaction Whitelists. Contract Interaction Rules take Smart Contract Whitelists. No other Rule takes Whitelists. Optional, multi-select. The Rule permits the combined set of their addresses
Amount threshold
Optional minimum and maximum, in the bound asset. Send, Contract Deployment and Contract Interaction Rules only, in single-asset Policies only
The Policy form caps Rule counts per operation type. You can add up to four Send Rules. Every other operation type allows one Rule. A Send Rule is always required. A single-asset Policy on Canton also requires a Receive Rule. See Limits.
When a Request is created, the first Rule in order that matches it applies. A Rule matches when all of these are true:
The amount is within its threshold, if it has one.
The destination is in its Whitelists, if it has any.
The Creator is in its initiator step.
Review creates the Policy Request and asks you to approve it on your Ledger device. Your approval is the first one. You then return to the page you came from, and the confirmation offers Copy link to request.
When the Master Administrator quorum approves the Request, the Policy appears in the list. It becomes selectable in the Account form, under Select policy. The form offers a Policy only when both of these are true:
The Policy is any-asset, or its asset is on the network of the Account.
The Policy has a Rule for every operation type the Account requires: Send, and also Receive on Canton.
If no Policy qualifies, Select policy is disabled and shows No existing policy.
Note: Write the description. It is what a colleague reads during an audit, months later, when the reasoning behind a quorum is no longer obvious.
Reading a Policy
When you open a Policy, the Policy details panel shows its name, description, Type and Asset. It has three tabs:
Rules, each with its operation type, initiator, approval steps and members, threshold where applicable, and its Whitelists. Each Whitelist shows its name and its number of entries.
Accounts, every Account that has adopted it. Check this before every edit. Operators see only Accounts they have visibility on.
Whitelists, every Whitelist any Rule points at. Administrators only.
Below the tabs, History lists the creation and edit Requests on this Policy, each with its review timeline. This is your audit trail.
While an edit Request is pending on the Policy, Edit policy is disabled and shows A request is already pending. Use as template stays available. The Policies list shows pending creation and edit Requests above the table, under a heading such as 2 requests in progress.
Editing a Policy
Name, description, and Rules are editable. The asset binding is not.
Review creates an edit Request, which you approve first. While it is pending, the Policy is locked against further edits. The lock applies to the interface and the API alike.
Once approved, the new Rules take effect on every adopting Account simultaneously. Requests created before the edit complete under the Rules that applied when they were created. Requests created after the edit is approved use the updated Rules.
Important: Read the Accounts tab first. A quorum change that is sensible for one Account may be unworkable for another that adopted the same Policy for different reasons.
Use as template
To create a sibling Policy, select Use as template from the list or the Policy detail. The create form opens pre-filled with the source's asset binding, description, and Rules, with the name left empty.
On a template the asset binding is editable, since the Policy does not exist yet. Converting single-asset to any-asset drops the thresholds; converting any-asset to single-asset gives you empty threshold fields to complete.
A banner on the form names the source Policy. The new Policy does not record its source.
What Policies do not do yet
No drafts. Either review or abandon; a closed form is not kept.
No archive or delete. Obsolete Policies stay in the list.
No creation from the Account form. Provision the Policy first.
No bulk assignment. Accounts adopt a Policy one at a time.
Read-only through the API. Policies can be read programmatically but not created or edited that way. The interface is the only write surface. See the API documentation.
Related
Last updated