Freeze and unfreeze balances
Restrict or release a holder address or part of a holder balance for approved custodian cases.
Freeze and unfreeze controls let a custodian restrict a holder without changing token ownership. An address freeze blocks the holder address entirely. A partial freeze locks a specific amount while leaving the rest of the balance free to move. A partial unfreeze releases some or all of the frozen amount when the approved case allows it.
Choose the right control
Start with the narrowest restriction that matches the approved case.
| Case | Use | Result |
|---|---|---|
| The holder address must not transfer | Address freeze | The platform restricts transfers on the address until the custodian releases it. |
| Only part of the holder's balance needs to stay locked | Partial freeze | The platform locks the selected amount. The rest of the holder's available balance can still move if normal transfer checks pass. |
| A previously frozen amount can be released | Partial unfreeze | The platform releases the selected amount from the holder's frozen balance. |
| The whole holder case is cleared | Address release plus any partial unfreeze still needed | The holder returns to the normal asset policy path after the custodian releases all restrictions. |
Use forced transfer only when the approved case requires moving tokens to another holder. See Forced transfer for that exception workflow.
Prerequisites
You need the Custodian role and the holder address for the case. Partial operations also require the amount, approval evidence, and custody sign-off.
What each control changes
| Control | What DALP changes | What stays with the case record |
|---|---|---|
| Address freeze | Queues a custodian transaction that sets the holder address freeze flag for the token. Set freeze to true to freeze the address and false to release it. | The platform does not decide whether the whole-address hold is justified. The operator must match the freeze or release to the approved case. |
| Partial freeze | Queues a custodian transaction that freezes a positive token amount for the holder. When the holder is present in the form's loaded balance data, the form blocks Continue and shows an inline error if the amount exceeds the holder's available balance, before the custodian submits the queued write. | The platform does not decide the legal hold amount. The operator must match the amount to the approved case. |
| Partial unfreeze | Queues a custodian transaction that releases a positive amount from the holder's frozen balance. | The platform does not decide whether the case is closed. The operator must keep the release approval with the case record. |
All three controls queue write operations. Reconcile the queued transaction status and holder balances before submitting another instruction for the same case.
Freeze or unfreeze a holder balance
Open the right holder-control surface
For address freeze, partial freeze, and partial unfreeze operations, authenticate with an account that has the Custodian role for the asset. For an address freeze, use the DALP API or CLI. For an address release, use the DALP API with the same holder address and freeze set to false. For a partial freeze or partial unfreeze, go to Asset Management, select the asset, then choose Manage Asset and open the partial freeze or partial unfreeze control.
dalp tokens freeze-address --address 0xTOKEN --target 0xHOLDER
dalp tokens freeze-partial --address 0xTOKEN --target 0xHOLDER --amount 1000000000000000000
dalp tokens unfreeze-partial --address 0xTOKEN --target 0xHOLDER --amount 1000000000000000000Select the holder address
For a partial freeze or partial unfreeze, the address field offers two ways to set the holder:
- Search suggests holder accounts for the asset. It lists participant accounts and leaves out the asset's own contract identities, such as the asset contract, claim issuers, and add-ons, so you do not pick a system address by mistake.
- Enter manually lets you type any address directly. Toggle back with Search instead.
Choose the holder address affected by the approved case. If the holder is not in the suggestions, verify the address and asset, then switch to manual entry and type it in. The control still acts on the address you set, so confirm it matches the approved case before you continue.
Enter the freeze state or amount
For an address freeze, confirm whether to freeze or release the holder address. For a partial freeze, enter a positive amount within the holder's available balance. For a partial unfreeze, enter a positive amount within the holder's currently frozen balance.
When you enter a partial-freeze amount for a holder that is present in the form's loaded balance data, the form compares the amount with that holder's available (unfrozen) balance before you can proceed. If the amount exceeds the available balance, the form blocks the Continue button and shows an inline error, so you fix the value before reaching the review step. An amount of zero or less also disables the button without that balance error. If the holder is not in the form's loaded balance data, the button stays enabled. On submit, the platform re-checks the amount against the holder's recorded available balance and rejects an over-balance freeze before queuing it; if the holder has no recorded balance, the on-chain check is the final backstop. Partial unfreeze skips the client-side balance comparison. It checks only that the amount is positive, and the on-chain processor enforces the frozen-balance limit when it processes the instruction.
Review and authenticate
Review the holder address, amount, and asset symbol. Authenticate with the required operator factor and submit only when the values match the approved case.
Reconcile the result
Check the queued transaction status, holder balance, and frozen balance before submitting another partial freeze or unfreeze for the same case.
Production checks
Before deploying these controls, limit the Custodian role to approved operators and define approved cases for each control type.
Require evidence for every decision. Reconcile queued write status and holder balances after each submission. Tie retries to the same instruction to avoid duplicate holds. Review open freezes against the case ledger on a regular schedule.
Troubleshooting
| Issue | What to check |
|---|---|
| Control not visible | Verify that your operator account has the Custodian role for the asset and that the asset supports holder restrictions. Address freeze and release are available through the DALP API; address freeze is also available through the CLI. |
| Address freeze did not clear a partial hold | Address freezes and partial freezes are separate controls. Release the partial frozen amount when the case allows it. |
| Holder address needs releasing | Use the address-freeze control in release mode, then reconcile holder status before allowing normal transfers. |
| Holder not in the search list | The picker suggests holder accounts only and hides contract identities. Verify the holder address and asset, then switch to manual entry to type the address directly. |
| Freeze amount rejected | When the holder is present in the form's loaded balance data, the form blocks Continue with an inline error if the amount exceeds the holder's available (unfrozen) balance; reduce the amount to within it. A zero or negative amount keeps Continue disabled. For a holder not in the form's loaded balance data, DALP re-checks a recorded balance on submit and rejects an over-balance freeze before queueing; if no balance is recorded, the on-chain check rejects it. |
| Unfreeze amount rejected | Check that the amount is positive and does not exceed the holder's frozen balance. |
| Holder still cannot transfer | Check address freeze state, remaining partial frozen amount, normal compliance checks, custody policy, and asset pause state. |
| Response lost after submit | Treat the instruction as pending until queued transaction status or holder balance proves the outcome. |
Related operations
For exception movements, see Forced transfer. For asset-level stop controls, see Pause and unpause an asset. For custodian permissions, see Per-Asset RBAC. For API use, see Token holders and transfers.