Skip to main content

Access Lists

Purpose​

Entity-level access lists provide two complementary mechanisms for controlling who can interact with an entity and its resources:

  • Blacklist: explicitly block known bad actors from transacting with this entity.
  • Trusted list: gate which counterparties are permitted to transact with this entity.

Both lists operate at the entity level. They apply to all wallets associated with the entity and are enforced during the authorization perimeter check that runs before every transaction executes.

Blacklist​

The blacklist is a set of wallet addresses that are prohibited from sending any transaction that targets this entity: including value transfers, contract invocations targeting the entity's resources, and wallet linking attempts.

Use Cases​

  • Bad actor blocking: block a known malicious wallet from sending tokens to or interacting with your entity.
  • Compromised wallet quarantine: if a wallet is suspected of compromise, blacklist it on all associated entities while recovery is in progress.
  • Regulatory compliance: block counterparties that violate jurisdictional requirements.
  • Dispute resolution: during a dispute, block a counterparty from further interaction until the dispute is resolved.

Behavior​

A blacklisted wallet address cannot:

  • Send value transfers (tokens) to any wallet associated with the blacklisting entity.
  • Invoke contracts owned by the entity.
  • Submit transactions that target the entity as a subject.

The blacklisted wallet can still transact freely on the network; it is blocked only from this entity's governance scope.

Trusted List​

The trusted list is a set of wallet addresses that are explicitly permitted to transact with this entity. When a trusted list is populated, it acts as an allowlist: only wallets on the list can transact with the entity.

Use Cases​

  • Counterparty gating: only pre-approved business partners can send tokens to or invoke contracts owned by this entity.
  • KYC/AML enforcement: only wallets that have completed identity verification (verified off-chain, then added to the trusted list) can interact.
  • Private governance: only council members on the trusted list can participate in proposal voting.
  • Supply chain permissioning: only known suppliers and buyers can execute transfers within a supply chain entity's scope.

Behavior​

When the trusted list is non-empty:

  • Only wallet addresses on the list can initiate transactions targeting this entity.
  • Wallets not on the list (even if they are otherwise valid) are rejected at the authorization perimeter.
  • The entity's own wallets are implicitly permitted (they are not required to be on the trusted list to manage the entity).

When the trusted list is empty:

  • No trusted-list restriction is enforced. Any non-blacklisted wallet can transact with the entity.

Managing Access Lists​

Access lists are managed via SET_ENTITY_ACCESS_LIST:

{
    "entityAddress": "<entity-address>",
    "operation": "ADD_BLACKLIST",
    "targetAddress": "<wallet-to-block>"
}
{
    "entityAddress": "<entity-address>",
    "operation": "REMOVE_BLACKLIST",
    "targetAddress": "<wallet-to-unblock>"
}
{
    "entityAddress": "<entity-address>",
    "operation": "ADD_TRUSTED",
    "targetAddress": "<wallet-to-allow>"
}
{
    "entityAddress": "<entity-address>",
    "operation": "REMOVE_TRUSTED",
    "targetAddress": "<wallet-to-remove>"
}

Operations:

OperationEffect
ADD_BLACKLISTAdd a wallet to the blacklist.
REMOVE_BLACKLISTRemove a wallet from the blacklist.
ADD_TRUSTEDAdd a wallet to the trusted list.
REMOVE_TRUSTEDRemove a wallet from the trusted list.

Only wallets with ManageAccessList = true permission on the entity can submit these transactions.

Authorization Perimeter Checks​

Access list checks are part of the authorization perimeter that runs at two points:

  1. Block validation: before transactions are accepted into a proposed block.
  2. Block execution: before each transaction is processed.

The check sequence:

1. Sender's entity ancestry chain must be fully enabled.
2. Is the sender on the target entity's blacklist?
   → Yes → reject transaction.
3. Is the target entity's trusted list non-empty?
   → Yes → is the sender on the trusted list?
      → No → reject transaction.
4. Is this a value transfer?
   → Does the recipient entity's access list block value transfers?
      → Yes → reject.
5. Proceed to capability checks and execution.

Access Lists and Agent Wallets​

Access lists are a useful tool for governing agent interaction at the entity level:

  • Add only the specific agent wallet addresses that are authorized to interact with an entity to its trusted list. Any new agent wallet that is created but not added to the trusted list cannot interact, even if it holds valid capabilities.
  • Use the blacklist to instantly revoke an agent's access to an entity without altering the agent wallet itself. This is useful when the agent wallet is shared across multiple entities and you want to revoke access to one without disabling the wallet entirely.

Combining blacklists, trusted lists, and capabilities provides defense in depth:

  • Capabilities gate what the wallet can do protocol-wide.
  • Trusted list gates which entities the wallet can interact with.
  • Blacklist provides an override that trumps both.