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