d-bis/explorer-monorepo
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a18918ce9121023af8b280f14daa1af5342117ff
explorer-monorepo/docs/API_DOCUMENTATION.md

11 KiB
Raw Blame History

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

Reference in New Issue View Git Blame Copy Permalink