Lock and unlock

Locks are emergency and compliance controls that freeze assets, wallets, or individual UTXOs. When locked, no transfers, reissues, or burns can proceed.

Lock scopes

AMP2 supports three levels of locking:

Asset lock / unlock

Lock prevents all send, reissue, and burn operations on the asset:

import {
  AmpLockAssetRequestSchema,
  AmpUnlockAssetRequestSchema,
  AmpActions,
} from '@blockstream/amp-registry';

// Lock
const lockResponse = await broadcastRequest<
  typeof AmpActions.lockAsset
>(
  AmpLockAssetRequestSchema.parse({
    action: 'edit',
    resource: `/amp/assets/${assetId}/lock`,
  }),
  broadcaster,
);

if (lockResponse.status !== 'success') {
  throw new Error(`Failed to lock asset: ${lockResponse.message}`);
}

// Unlock
const unlockResponse = await broadcastRequest<
  typeof AmpActions.unlockAsset
>(
  AmpUnlockAssetRequestSchema.parse({
    action: 'edit',
    resource: `/amp/assets/${assetId}/unlock`,
  }),
  broadcaster,
);

if (unlockResponse.status !== 'success') {
  throw new Error(`Failed to unlock asset: ${unlockResponse.message}`);
}

Wallet lock / unlock

Lock prevents all transfers from a specific wallet:

// Lock wallet
await broadcastRequest({
  action: 'edit',
  resource: `/amp/wallets/${wid}/lock`,
  details: {},
}, broadcaster);

// Unlock wallet
await broadcastRequest({
  action: 'edit',
  resource: `/amp/wallets/${wid}/unlock`,
  details: {},
}, broadcaster);

UTXO lock / unlock

Lock a specific unspent output, identified by txid:vout:

// Lock UTXO
await broadcastRequest({
  action: 'edit',
  resource: `/amp/assets/${assetId}/utxos/${outpoint}/lock`,
  details: {},
}, broadcaster);

// Unlock UTXO
await broadcastRequest({
  action: 'edit',
  resource: `/amp/assets/${assetId}/utxos/${outpoint}/unlock`,
  details: {},
}, broadcaster);

The outpoint format is txid:vout (e.g., a1b2c3...d4e5:0).

When to use locks

• Incident response: freeze an asset immediately while investigating suspicious activity.
• Lost key recovery: lock a wallet while arranging reissuance to a new wallet.
• Compliance holds: lock specific UTXOs or wallets pending regulatory resolution.
• Corporate actions: lock the asset during settlement windows, dividend calculations, or maturity events.

Interaction with restrictions

Locks and restrictions are independent:

• A locked asset blocks everything. Restrictions do not override a lock.
• An unlocked asset with restrictions still enforces the whitelist and burn rules.
• Unlocking does not change restriction policies.

Operational guidance

• Record lock/unlock events in your issuer audit systems with operator, timestamp, and reason.
• Communicate locks to affected parties (investors, venues) through your own channels: AMP2 does not send notifications.
• Test lock/unlock on testnet: verify that locked assets and wallets correctly block operations.
• Keep unlock access tightly controlled: consider requiring multi person authorization in your issuer systems before calling the unlock endpoint.

Next steps

• Monitoring: track lock states and transaction history
• Restrictions: transfer policy controls
• Best Practices: operational recommendations