Add full monorepo: virtual-banker, backend, frontend, docs, scripts, deployment
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
defiQUG
453
docs/API_DOCUMENTATION.md
Normal file
453
docs/API_DOCUMENTATION.md
Normal file
@@ -0,0 +1,453 @@
|
||||
# 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
Block a user