explorer-monorepo/docs/API_DOCUMENTATION.md

API Documentation

Date: 2025-12-24
Status: Complete API documentation for all contracts

---

Overview

This document provides comprehensive API documentation for all contracts in the system.

---

Legal Compliance Contracts

LegallyCompliantBase

Location: contracts/compliance/LegallyCompliantBase.sol

Functions

recordLegalNotice(string calldata message)

Record a legal notice.

Parameters:

• message: Legal notice message

Access: DEFAULT_ADMIN_ROLE only

Events: LegalNotice(bytes32 indexed noticeHash, string message, uint256 timestamp)

_generateLegalReferenceHash(address from, address to, uint256 value, bytes memory additionalData)

Generate a legal reference hash for a value transfer.

Parameters:

• from: Source address
• to: Destination address
• value: Transfer amount
• additionalData: Additional data

Returns: bytes32 - Legal reference hash

Access: Internal

_emitCompliantValueTransfer(address from, address to, uint256 value, string memory legalReference, bytes32 iso20022MessageId)

Emit a compliant value transfer event.

Parameters:

• from: Source address
• to: Destination address
• value: Transfer amount
• legalReference: Legal reference string
• iso20022MessageId: ISO 20022 message ID

Access: Internal

Events

• LegalNotice(bytes32 indexed noticeHash, string message, uint256 timestamp)
• ValueTransferDeclared(address indexed from, address indexed to, uint256 value, bytes32 legalReferenceHash)
• JurisdictionDeclared(string jurisdiction, uint256 timestamp)
• DisputeResolutionMechanismSet(string mechanism, uint256 timestamp)

Constants

• LEGAL_FRAMEWORK_VERSION: "1.0.0"
• LEGAL_JURISDICTION: "International Private Law"
• DISPUTE_RESOLUTION_MECHANISM: "ICC Arbitration (Paris)"
• ISO_20022_COMPLIANCE: ISO 20022 compliance statement
• TRAVEL_RULE_EXEMPTION_STATEMENT: Travel Rules exemption statement
• REGULATORY_EXEMPTION_STATEMENT: Regulatory exemption statement

---

ComplianceRegistry

Location: contracts/compliance/ComplianceRegistry.sol

Functions

registerContract(address contractAddress)

Register a contract that inherits from LegallyCompliantBase.

Parameters:

• contractAddress: Address of the compliant contract

Access: REGISTRAR_ROLE only

Events: ContractRegistered(address indexed contractAddress, string legalFrameworkVersion, string legalJurisdiction, uint256 timestamp)

updateContractCompliance(address contractAddress, bytes32 newLegalNoticeHash)

Update compliance status with a new legal notice.

Parameters:

• contractAddress: Address of the compliant contract
• newLegalNoticeHash: Hash of the new legal notice

Access: REGISTRAR_ROLE only

Events: ContractComplianceUpdated(address indexed contractAddress, bytes32 lastLegalNoticeHash, uint256 timestamp)

getContractComplianceStatus(address contractAddress)

Get compliance status for a contract.

Parameters:

• contractAddress: Address of the contract

Returns: ContractComplianceStatus struct

isContractRegistered(address contractAddress)

Check if a contract is registered.

Parameters:

• contractAddress: Address of the contract

Returns: bool - True if registered

---

Token Contracts

CompliantUSDT

Location: contracts/tokens/CompliantUSDT.sol

Functions

pause()

Pause token transfers.

Access: Owner only

unpause()

Unpause token transfers.

Access: Owner only

mint(address to, uint256 amount)

Mint new tokens.

Parameters:

• to: Address to mint tokens to
• amount: Amount of tokens to mint

Access: Owner only

burn(uint256 amount)

Burn tokens from caller's balance.

Parameters:

• amount: Amount of tokens to burn

Access: Public

Standard ERC20 Functions

• transfer(address to, uint256 amount)
• transferFrom(address from, address to, uint256 amount)
• approve(address spender, uint256 amount)
• balanceOf(address account)
• totalSupply()
• decimals() - Returns 6

---

CompliantUSDC

Location: contracts/tokens/CompliantUSDC.sol

Same API as CompliantUSDT.

---

Utility Contracts

TokenRegistry

Location: contracts/utils/TokenRegistry.sol

Functions

registerToken(address tokenAddress, string calldata name, string calldata symbol, uint8 decimals, bool isNative, address bridgeAddress)

Register a new token.

Parameters:

• tokenAddress: Address of the token contract
• name: Token name
• symbol: Token symbol
• decimals: Number of decimals
• isNative: Whether this is a native token
• bridgeAddress: Bridge address if bridged (address(0) if not)

Access: REGISTRAR_ROLE only

updateTokenStatus(address tokenAddress, bool isActive)

Update token status.

Parameters:

• tokenAddress: Address of the token
• isActive: New active status

Access: REGISTRAR_ROLE only

removeToken(address tokenAddress)

Remove a token from the registry.

Parameters:

• tokenAddress: Address of the token

Access: REGISTRAR_ROLE only

getTokenInfo(address tokenAddress)

Get token information.

Parameters:

• tokenAddress: Address of the token

Returns: TokenInfo struct

getTokenBySymbol(string calldata symbol)

Get token address by symbol.

Parameters:

• symbol: Token symbol

Returns: address - Token address (address(0) if not found)

isTokenRegistered(address tokenAddress)

Check if a token is registered.

Parameters:

• tokenAddress: Address of the token

Returns: bool - True if registered

isTokenActive(address tokenAddress)

Check if a token is active.

Parameters:

• tokenAddress: Address of the token

Returns: bool - True if active

getAllTokens()

Get all registered tokens.

Returns: address[] - Array of token addresses

getTokenCount()

Get count of registered tokens.

Returns: uint256 - Number of registered tokens

---

FeeCollector

Location: contracts/utils/FeeCollector.sol

Functions

collectFees(address token, uint256 amount)

Collect fees in a token.

Parameters:

• token: Token address (address(0) for native ETH)
• amount: Amount to collect

Access: Public (payable for ETH)

distributeFees(address token)

Distribute collected fees to recipients.

Parameters:

• token: Token address (address(0) for native ETH)

Access: FEE_MANAGER_ROLE only

addFeeRecipient(address token, address recipient, uint256 shareBps)

Add a fee recipient for a token.

Parameters:

• token: Token address (address(0) for native ETH)
• recipient: Recipient address
• shareBps: Share in basis points (10000 = 100%)

Access: FEE_MANAGER_ROLE only

removeFeeRecipient(address token, address recipient)

Remove a fee recipient.

Parameters:

• token: Token address
• recipient: Recipient address to remove

Access: FEE_MANAGER_ROLE only

getFeeRecipients(address token)

Get fee recipients for a token.

Parameters:

• token: Token address

Returns: FeeRecipient[] - Array of fee recipients

getTotalCollected(address token)

Get total collected fees for a token.

Parameters:

• token: Token address

Returns: uint256 - Total collected amount

getTotalDistributed(address token)

Get total distributed fees for a token.

Parameters:

• token: Token address

Returns: uint256 - Total distributed amount

getBalance(address token)

Get current balance for a token.

Parameters:

• token: Token address (address(0) for native ETH)

Returns: uint256 - Current balance

emergencyWithdraw(address token, address to, uint256 amount)

Emergency withdraw (admin only).

Parameters:

• token: Token address (address(0) for native ETH)
• to: Recipient address
• amount: Amount to withdraw

Access: DEFAULT_ADMIN_ROLE only

---

AddressMapper

Location: contracts/utils/AddressMapper.sol

Functions

getDeployedAddress(address genesisAddress)

Get the deployed address for a genesis address.

Parameters:

• genesisAddress: The address from genesis.json

Returns: address - The actual deployed address

getGenesisAddress(address deployedAddress)

Get the genesis address for a deployed address.

Parameters:

• deployedAddress: The deployed address

Returns: address - The genesis address

isMapped(address addr)

Check if an address is a genesis address that has been mapped.

Parameters:

• addr: Address to check

Returns: bool - True if the address has a mapping

setMapping(address genesisAddress, address deployedAddress)

Add or update a mapping (owner only).

Parameters:

• genesisAddress: The genesis address
• deployedAddress: The deployed address

Access: Owner only

removeMapping(address genesisAddress)

Remove a mapping (owner only).

Parameters:

• genesisAddress: The genesis address to remove

Access: Owner only

transferOwnership(address newOwner)

Transfer ownership (owner only).

Parameters:

• newOwner: The new owner address

Access: Owner only

---

Error Codes

ComplianceRegistry

• "ComplianceRegistry: zero address" - Zero address provided
• "ComplianceRegistry: contract already registered" - Contract already registered
• "ComplianceRegistry: contract not registered" - Contract not registered

TokenRegistry

• "TokenRegistry: zero address" - Zero address provided
• "TokenRegistry: token already registered" - Token already registered
• "TokenRegistry: symbol already used" - Symbol already in use
• "TokenRegistry: invalid token contract" - Invalid token contract
• "TokenRegistry: token not registered" - Token not registered

FeeCollector

• "FeeCollector: ETH amount mismatch" - ETH amount mismatch
• "FeeCollector: no ETH expected" - No ETH expected
• "FeeCollector: no recipients configured" - No recipients configured
• "FeeCollector: no fees to distribute" - No fees to distribute
• "FeeCollector: ETH transfer failed" - ETH transfer failed
• "FeeCollector: distribution overflow" - Distribution overflow
• "FeeCollector: zero recipient" - Zero recipient address
• "FeeCollector: invalid share" - Invalid share percentage
• "FeeCollector: recipient already exists" - Recipient already exists
• "FeeCollector: recipient not found" - Recipient not found

---

Events Reference

ComplianceRegistry

• ContractRegistered(address indexed contractAddress, string legalFrameworkVersion, string legalJurisdiction, uint256 timestamp)
• ContractComplianceUpdated(address indexed contractAddress, bytes32 lastLegalNoticeHash, uint256 timestamp)

TokenRegistry

• TokenRegistered(address indexed tokenAddress, string name, string symbol, uint8 decimals, uint256 timestamp)
• TokenUpdated(address indexed tokenAddress, bool isActive, uint256 timestamp)
• TokenRemoved(address indexed tokenAddress, uint256 timestamp)

FeeCollector

• FeesCollected(address indexed token, address indexed from, uint256 amount, uint256 timestamp)
• FeesDistributed(address indexed token, address indexed recipient, uint256 amount, uint256 timestamp)
• FeeRecipientAdded(address indexed token, address indexed recipient, uint256 shareBps, uint256 timestamp)
• FeeRecipientRemoved(address indexed token, address indexed recipient, uint256 timestamp)

---

Last Updated: 2025-12-24