مستندات داراClawback policy
Clawback lets the issuer take a customer's tokens back on-chain. It is the most severe power the platform holds over
customer property, so it is narrow by policy, slow by design and public by construction. It exists because every
Dara asset is issued with AUTH_CLAWBACK_ENABLED (STELLAR_ARCHITECTURE.md §2, ASSET_CONFIGURATION.md): the flag
cannot be added after trustlines exist, and without it a court order or a lost custody key could not be honoured.
Why it exists
| Use | Example |
|---|---|
| Court or regulator order | A binding order to seize or return a customer's holding |
| Key recovery | A custody key is lost or must be retired: claw back from the old account, re-issue to the new one (AUTHORITY_MATRIX.md §2) |
| Theft containment | Tokens moved by a leaked key to one of our accounts without an intent (the indexer raises CRITICAL); claw back, then re-issue to the rightful holder |
It is never used for fees, disputes between customers, pricing errors or anything a ledger correction can fix.
Who and how
| Step | Who | Enforced by |
|---|---|---|
| Request (customer, asset, quantity, reason, legal or recovery reference) | COMPLIANCE_OFFICER | clawback.Request; refused without a reference, above the available balance, for an asset that is not issued, or while another clawback for the same customer and asset is open (unique index) |
| Approve or reject | A different COMPLIANCE_OFFICER | RequireDifferent, and CHECK (decided_by <> requested_by) in the database |
| Chain check before anyone signs | System | The trustline exists, is clawback-enabled and holds at least the quantity |
| Hold | System | Approval moves the quantity from the customer's available to held tokens: it can no longer be sold or transferred |
On-chain Clawback | The issuer's medium threshold (launch: the one human signer; with four signers, 2 of 4), on their own keys, after verifying the envelope (Signing page) | The issuer's thresholds on-chain; the platform holds no issuer key |
| Settlement | System, exactly once when applied in a closed ledger | TOKEN_SUPPLY and the customer's held tokens fall by the quantity |
| Failure or expiry | System | The hold is released; nothing moved |
Legal or business approval outside the platform (counsel, the board, the regulator) is recorded as the
legal_reference; the platform does not decide whether an order is valid. Operations must not request a clawback
without that approval in hand.
Financial effect
The clawed-back tokens are destroyed: supply falls and the backing that stood behind them becomes free (visible as "issuable" on the Overview). The platform pays nothing automatically. Compensation, if the order or recovery case requires it, is a separate maker-checker cash entry with its own reference. For key recovery, the follow-up is an ISSUE of the same quantity to the customer's new account path, under the normal issuance controls.
Disclosure
Customers are told before they hold anything: the landing site and the wallet state that the issuer can claw tokens
back by court order or for key recovery, that it needs the signature of the issuer's human signer (one person at launch), and that it is public on-chain. The
stellar.toml of each asset states the freeze and clawback powers (SEP-1). Dara Scan shows every clawback.
Audit and incident process
Every step is an audit event (clawback.request, .approve / .reject, .completed / .failed,
.reconciliation_required) with actor, reason and reference. The indexer links the on-chain clawback to its intent
through the MEMO_HASH; a clawback without a matching intent is an unexplained movement: a CRITICAL incident that
stops trading, handled as a suspected issuer-key compromise (INCIDENT_RESPONSE.md). Reconciliation after a clawback
must pass; if it does not, issuance stays blocked until the difference is explained.
Tests
backend/internal/e2e/clawback_integration_test.go (local Stellar): unauthorized role, amount above the balance,
asset not issued, missing reference, partial clawback, duplicate open request, self-approval, the hold blocking a
transfer, a second decision refused, exactly-once settlement on chain and ledger, reconciliation and indexer
agreement, the audit trail, and a rejected request moving nothing. dara demo step 14 does the same over the HTTP
API with the stand-in signers.