Handling Sanctioned Addresses

The decision to facilitate a transaction from or to Bitcoin must take into account sanctioned addresses. For deposits, each validator screens a deposit while it waits in the approval queue, before deciding whether to vote to accept it; see When sanctions checks apply and Screening with TRM Labs.

Checking if an address is sanctioned

Each member of the committee might have different risk tolerances or policies for which set of addresses they do not want to serve. To accommodate different validator preferences, the Hashi node software has a configurable mechanism for determining whether to deny service to a particular address.

Screening with TRM Labs

Each node operator screens with their own TRM Labs account. To set up screening:

1. Create a TRM Labs account.
2. Create an API key in the TRM platform under Settings > API Tokens.
3. Set the key as trm-api-key in the node config.

Without a key, the node does not screen. TRM only covers Mainnet, so the node ignores the key on other networks.

The following table lists what the node screens in each flow and which TRM API it uses:

Flow	What the node screens	TRM API
Deposit	The Bitcoin transaction into the deposit address	Transaction Monitoring (POST /public/v2/tm/transfers)
Deposit	The Sui address credited with hBTC	Wallet Screening (POST /public/v2/screening/addresses)
Withdrawal	The Bitcoin destination address	Wallet Screening
Withdrawal	The Sui address that requested the withdrawal	Wallet Screening

A node does not vote for a deposit or withdrawal when:

• TRM attributes a screened address itself (risk type OWNERSHIP) to a category scored High or Severe. Exposure only through counterparties or intermediaries does not count.
• The deposit's transfer raises an alert at High or Severe.
• TRM cannot screen the transfer, or rejects the request.

The node logs why. The leader asking for its vote learns only that the node's sanctions check has not approved the request.

Transaction Monitoring is asynchronous. A node waits up to 10 seconds for TRM to finish screening a deposit's transfer; if TRM is still processing it, the node declines the deposit for now and the leader retries on the next Bitcoin block. Timeouts, rate limits and TRM server errors are also retried, and the node does not vote in the meantime. TRM can still alert on a transfer after the committee approves the deposit; hashi does not revisit an approval.

A node reuses TRM's answer for the same set of addresses for 5 minutes by default (trm-verdict-reuse-ms, at most an hour) instead of asking TRM again, so a vote can rest on a verdict that old. Each committee member, and the node itself, may also spend only a limited number of TRM calls at a node (trm-per-caller-burst, trm-per-caller-refill-per-sec); past that limit the node declines for now and the request is retried, as during a TRM outage.

When sanctions checks apply

Deposits: When a user submits a deposit request, their request sits in a queue or waiting room until the validators vote on accepting that deposit and minting an appropriate amount of hBTC. Sanctions checking happens at the time a validator decides whether to vote for accepting a deposit. If a validator decides that it does not want to service that deposit, it does not vote for it and ignores that the deposit exists. If a quorum decides to accept a deposit that a particular validator did not want to accept, per protocol the validator must recognize (and subsequently make use of) the deposited BTC.

Withdrawals: When a user submits a withdraw request, their request sits in a queue or waiting room until the validators pick it up for processing. Before selecting a request for processing, the validators vote on approving the request. One of the required checks as part of voting for approval is performing sanctions checking. After a quorum of validators has voted to approve a request, a node can pick it up for processing. If a quorum decides to approve a request for processing, per protocol all validators must assist in driving the request to completion.

Tainted UTXOs

The Hashi protocol implements rigorous sanctions enforcement, but enforcement is ultimately best-effort. A quorum of validators might accept a deposit that one validator preferred to not accept, or a previous committee accepted a deposit that the current committee would have rejected. In either case, after Hashi accepts a UTXO into its pool, the protocol treats it as its own, and it must be available during coin selection to process withdraw requests.