Identity Lists
IdentityAllowList, IdentityBlockList, and AddressBlockList modules for granular access control. Covers private placement whitelists, sanctions screening, and the distinction between identity-level and address-level blocking.
Purpose: Reference for identity-based list compliance modules.
- Doc type: Reference
- What you'll find here:
- IdentityAllowList, IdentityBlockList, and AddressBlockList — granular access control
- Interface tables showing on-chain capabilities
- Identity-level vs address-level blocking comparison
- Key invariants, operational signals, and failure modes
- Related: Compliance Overview, Identity Verification, Country Restrictions, Supply & Investor Limits, TimeLock, Asset Contracts
Where these modules apply
| Concern | IdentityAllowList | IdentityBlockList | AddressBlockList |
|---|---|---|---|
| Minting | Checks recipient identity | Checks recipient identity | Checks recipient address |
| Transfers | Checks recipient identity | Checks recipient identity | Checks recipient address |
| Burns | — | — | — |
| Forced transfers | — | — | — |
Modules
| Module | Granularity | Purpose |
|---|---|---|
| IdentityAllowList | Identity contract | Whitelist specific investors by OnchainID contract address |
| IdentityBlockList | Identity contract | Block specific investors by OnchainID contract address |
| AddressBlockList | Wallet address | Block specific wallet addresses (without requiring identity) |
Identity-level vs address-level
| Aspect | IdentityAllowList / IdentityBlockList | AddressBlockList |
|---|---|---|
| Granularity | Per identity (investor) | Per wallet address |
| Covers all wallets | Yes — one identity may have multiple wallets | No — wallet-specific |
| Requires identity | Yes | No |
| Bypassed by new wallet | No — identity persists across wallets | Yes — new wallet address bypasses |
| Primary use case | Private placements, institutional-only | Sanctions lists (OFAC SDN), fraud prevention |
When to block at identity vs address:
- Identity-level blocking is more robust for compliance violations or legal disputes — it follows the investor across all their registered wallets
- Address-level blocking is appropriate for immediate sanctions screening where speed matters and the specific wallet address is the sanctioned entity
Interface (capabilities)
IdentityAllowList
| Capability | Who can call | Inputs | On-chain effect | Emits | Notes |
|---|---|---|---|---|---|
setModuleParameters | Token admin (via compliance) | Array of OnchainID contract addresses | Stores allowed identity list | — | Empty list blocks all transfers |
canTransfer | Compliance engine | Sender, recipient, amount | Checks recipient's identity against allowed list | — | Identity resolved from registry |
IdentityBlockList
| Capability | Who can call | Inputs | On-chain effect | Emits | Notes |
|---|---|---|---|---|---|
setModuleParameters | Token admin (via compliance) | Array of OnchainID contract addresses | Stores blocked identity list | — | Empty list blocks none |
canTransfer | Compliance engine | Sender, recipient, amount | Checks recipient's identity against blocked list | — | Identity resolved from registry |
AddressBlockList
| Capability | Who can call | Inputs | On-chain effect | Emits | Notes |
|---|---|---|---|---|---|
setModuleParameters | Token admin (via compliance) | Array of wallet addresses | Stores blocked address list | — | No identity lookup required |
canTransfer | Compliance engine | Sender, recipient, amount | Checks recipient (_to) address against blocked list | — | Reverts with "Receiver address blocked" |
Use cases
IdentityAllowList — private placement
Restrict a token to pre-approved investors by OnchainID address. Used for Reg D 506(b) private placements, institutional-only offerings, and friends-and-family rounds.
IdentityBlockList — compliance violations
Block a specific investor across all their wallets. Used for compliance alerts, failed re-KYC, and court orders.
AddressBlockList — sanctions screening
Block specific wallet addresses matching OFAC SDN or similar sanctions lists, known fraud addresses, or mixer/tumbler addresses flagged by on-chain analytics.
Key invariants
- IdentityAllowList with an empty list blocks ALL transfers
- IdentityBlockList with an empty list blocks NONE
- AddressBlockList checks the recipient wallet address directly, without identity lookup
- These modules can be combined: e.g., IdentityAllowList for private placement + AddressBlockList for OFAC screening
Operational signals
No events emitted by these modules. Monitor for ComplianceCheckFailed revert errors in failed transactions when transfers violate list restrictions.
Failure modes & edge cases
- IdentityAllowList with an empty list silently blocks all transfers — ensure the list is populated before activating
- Adding an investor to IdentityBlockList does not freeze their existing balance — they cannot receive new tokens but can still transfer out (unless other modules block)
- AddressBlockList can be bypassed by the blocked investor using a different wallet address — use IdentityBlockList for persistent blocking
See also
- Compliance Overview — module architecture and regulatory templates
- Identity Verification — claim-based verification alternative to explicit lists
- Country Restrictions — jurisdiction-level blocking
- Supply & Investor Limits — InvestorCount limits complement identity lists
- TimeLock — holding period enforcement
Country Restrictions
CountryAllowList and CountryBlockList modules for geographic transfer restrictions. Covers sanctions/OFAC use cases, EU MiCA jurisdiction selection, and ISO 3166-1 country codes.
Identity Verification
SMARTIdentityVerification module with full RPN expression system. Covers KYC/AML/ACCREDITED/CONTRACT claim topics, AND/OR/NOT operators, exemption support, and real-world expression examples.