Transfer Guard

The TransferGuard is the compliance layer of the Grunt protocol. It validates token transfers — including mints, burns, and regular transfers — against configurable rules that determine which addresses are allowed to hold or transfer tokens. Any token in the system (Position Manager shares, wrapped assets, LP tokens) can be placed under a TransferGuard’s control.

Two Modes of Operation

Each token registered with a TransferGuard operates in one of two modes:

Blocklist Mode

In blocklist mode, everyone is allowed by default. Only addresses that have been explicitly added to the blocklist are restricted. This is the more permissive mode — it assumes all addresses are compliant unless flagged otherwise.

Use case: a broadly accessible token where the operator only needs to block specific sanctioned or problematic addresses.

Whitelist Mode

In whitelist mode, no one is allowed by default. Only addresses that have been explicitly added to the whitelist are permitted. This is the more restrictive mode — it assumes no address is compliant unless explicitly approved.

Use case: a restricted token that should only be held by KYC/KYB-verified addresses.

Address Statuses

Every address has one of three statuses relative to a TransferGuard:

NONE — the default status for any address that has not been explicitly configured. In blocklist mode, NONE means allowed. In whitelist mode, NONE means blocked.

WHITELIST — the address is explicitly approved. This status means the address is allowed in both modes. In blocklist mode, it has no additional effect (since NONE addresses are already allowed). In whitelist mode, it is required for the address to participate.

BLOCKLIST — the address is explicitly blocked. This status means the address is blocked in both modes, regardless of which mode the token operates in.

Summary:

Address Status	Blocklist Mode	Whitelist Mode
NONE	Allowed	Blocked
WHITELIST	Allowed	Allowed
BLOCKLIST	Blocked	Blocked

Address statuses are global to the TransferGuard, not per-token. If an address is blocklisted, it is blocklisted for every token governed by that guard. Statuses can be set individually or in batches.

How Transfer Validation Works

When a token transfer occurs, the TransferGuard evaluates it based on the type of transfer:

Minting (new tokens being created) — only the recipient (to address) is checked. The rationale: tokens are entering circulation, and the guard needs to confirm the recipient is allowed to hold them.

Burning (tokens being destroyed) — only the sender (from address) is checked. The rationale: tokens are leaving circulation, and the guard needs to confirm the sender is a known, compliant participant.

Regular transfer (tokens moving between addresses) — both the sender and recipient are checked. Both must pass the compliance rules for the transfer to proceed.

For each address checked, the guard evaluates:

1. Is the address explicitly blocklisted? If yes, the transfer is rejected.
2. Is the address explicitly whitelisted? If yes, the address passes.
3. Is the token in blocklist mode? If yes, the address passes (since NONE addresses are allowed in blocklist mode).
4. Otherwise (whitelist mode, NONE status), the transfer is rejected.

Pause Capability

Beyond address-level controls, the TransferGuard can pause any token it governs. When a token is paused:

• All transfers are blocked — mints, burns, and regular transfers
• No exceptions, regardless of address status
• The pause applies to that specific token only (other tokens under the same guard are unaffected)

Pausing is an emergency mechanism. It is designed for situations where all activity on a token needs to stop immediately — for example, if a security issue is discovered or a regulatory hold is required.

The pause can be activated by the guard’s owner or a designated pauser role, and removed when the situation is resolved.

How It Connects to the Protocol

The TransferGuard integrates with the rest of Grunt in several places:

• Position Manager shares — when a guard is set on a Position Manager, every share transfer (including mints from deposits and burns from exits) is validated. The Position Manager also checks the guard’s pause state before allowing deposits, withdrawals, or rebalancing.
• Wrapped assets — tokens like wUSCC can be placed under a guard to ensure they only move between compliant addresses.
• Facility LP tokens — the guard key on an intent determines which TransferGuard governs the LP tokens for that intent.

All TransferGuards are deployed via a factory using the beacon proxy pattern, allowing gas-efficient deployment and coordinated upgrades across all instances.