d-bis/explorer-monorepo
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add full monorepo: virtual-banker, backend, frontend, docs, scripts, deployment

Browse Source 
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
defiQUG
2026-02-10 11:32:49 -08:00
parent 4d4f8cedad
commit 903c03c65b
815 changed files with 125522 additions and 264 deletions
Download Patch File Download Diff File Expand all files Collapse all files

459
docs/INTEGRATION_GUIDES.md Normal file
View File

@@ -0,0 +1,459 @@
# Integration Guides
**Date**: 2025-12-24
**Status**: Complete integration guides for all contracts
---
## Overview
This document provides integration guides for developers who want to integrate with the deployed contracts.
---
## Integration with Compliant Tokens
### Using CompliantUSDT or CompliantUSDC
#### 1. Import the Contract Interface
```solidity
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.19;
import "@openzeppelin/contracts/token/ERC20/IERC20.sol";
import "../tokens/CompliantUSDT.sol";
contract MyContract {
IERC20 public usdt;
constructor(address usdtAddress) {
usdt = IERC20(usdtAddress);
}
function transferUSDT(address to, uint256 amount) external {
usdt.transfer(to, amount);
}
}
```
#### 2. Handle Pausable State
```solidity
import "@openzeppelin/contracts/security/Pausable.sol";
import "../tokens/CompliantUSDT.sol";
contract MyContract {
CompliantUSDT public usdt;
function transferUSDT(address to, uint256 amount) external {
require(!usdt.paused(), "USDT is paused");
usdt.transfer(to, amount);
}
}
```
#### 3. Listen to Compliance Events
```solidity
contract MyContract {
event ValueTransferDetected(
address indexed from,
address indexed to,
uint256 value,
bytes32 legalReferenceHash
);
function onValueTransferDeclared(
address from,
address to,
uint256 value,
bytes32 legalReferenceHash
) external {
emit ValueTransferDetected(from, to, value, legalReferenceHash);
}
}
```
---
## Integration with TokenRegistry
### 1. Query Token Information
```solidity
import "../utils/TokenRegistry.sol";
contract MyContract {
TokenRegistry public tokenRegistry;
constructor(address registryAddress) {
tokenRegistry = TokenRegistry(registryAddress);
}
function getTokenInfo(address token) external view returns (TokenRegistry.TokenInfo memory) {
return tokenRegistry.getTokenInfo(token);
}
function isTokenActive(address token) external view returns (bool) {
return tokenRegistry.isTokenActive(token);
}
function findTokenBySymbol(string calldata symbol) external view returns (address) {
return tokenRegistry.getTokenBySymbol(symbol);
}
}
```
### 2. Register Your Token
```solidity
contract MyToken {
TokenRegistry public tokenRegistry;
constructor(address registryAddress) {
tokenRegistry = TokenRegistry(registryAddress);
}
function registerInRegistry() external {
// This should be called by the token registry owner
tokenRegistry.registerToken(
address(this),
"My Token",
"MTK",
18,
false, // not native
address(0) // not bridged
);
}
}
```
---
## Integration with FeeCollector
### 1. Collect Fees
```solidity
import "../utils/FeeCollector.sol";
import "@openzeppelin/contracts/token/ERC20/IERC20.sol";
contract MyContract {
FeeCollector public feeCollector;
IERC20 public feeToken;
constructor(address collectorAddress, address tokenAddress) {
feeCollector = FeeCollector(collectorAddress);
feeToken = IERC20(tokenAddress);
}
function collectFees(uint256 amount) external {
// Approve first
feeToken.approve(address(feeCollector), amount);
// Collect fees
feeCollector.collectFees(address(feeToken), amount);
}
function collectETHFees() external payable {
feeCollector.collectFees{value: msg.value}(address(0), msg.value);
}
}
```
### 2. Query Fee Information
```solidity
contract MyContract {
FeeCollector public feeCollector;
function getFeeStats(address token) external view returns (
uint256 totalCollected,
uint256 totalDistributed,
uint256 currentBalance
) {
totalCollected = feeCollector.getTotalCollected(token);
totalDistributed = feeCollector.getTotalDistributed(token);
currentBalance = feeCollector.getBalance(token);
}
}
```
---
## Integration with ComplianceRegistry
### 1. Check Contract Compliance
```solidity
import "../compliance/ComplianceRegistry.sol";
contract MyContract {
ComplianceRegistry public complianceRegistry;
constructor(address registryAddress) {
complianceRegistry = ComplianceRegistry(registryAddress);
}
function isContractCompliant(address contractAddress) external view returns (bool) {
return complianceRegistry.isContractRegistered(contractAddress);
}
function getComplianceInfo(address contractAddress) external view returns (
bool isRegistered,
string memory frameworkVersion,
string memory jurisdiction
) {
ComplianceRegistry.ContractComplianceStatus memory status =
complianceRegistry.getContractComplianceStatus(contractAddress);
return (
status.isRegistered,
status.legalFrameworkVersion,
status.legalJurisdiction
);
}
}
```
### 2. Register Your Contract
If your contract inherits from `LegallyCompliantBase`, it can be registered:
```solidity
import "../compliance/LegallyCompliantBase.sol";
import "../compliance/ComplianceRegistry.sol";
contract MyCompliantContract is LegallyCompliantBase {
ComplianceRegistry public complianceRegistry;
constructor(address admin, address registryAddress) LegallyCompliantBase(admin) {
complianceRegistry = ComplianceRegistry(registryAddress);
}
function registerSelf() external {
// This should be called by the registry owner
complianceRegistry.registerContract(address(this));
}
}
```
---
## Integration with AddressMapper
### 1. Map Addresses
```solidity
import "../utils/AddressMapper.sol";
contract MyContract {
AddressMapper public addressMapper;
constructor(address mapperAddress) {
addressMapper = AddressMapper(mapperAddress);
}
function getActualAddress(address genesisAddress) external view returns (address) {
return addressMapper.getDeployedAddress(genesisAddress);
}
function checkIfMapped(address addr) external view returns (bool) {
return addressMapper.isMapped(addr);
}
}
```
---
## Frontend Integration
### 1. Web3.js Integration
```javascript
const { ethers } = require('ethers');
// Connect to provider
const provider = new ethers.providers.JsonRpcProvider('http://192.168.11.250:8545');
// Get contract instance
const usdtAbi = [...]; // ABI from contract
const usdtAddress = '0x...'; // Deployed address
const usdt = new ethers.Contract(usdtAddress, usdtAbi, provider);
// Read operations
const balance = await usdt.balanceOf(userAddress);
const totalSupply = await usdt.totalSupply();
const isPaused = await usdt.paused();
// Write operations (need signer)
const signer = provider.getSigner();
const usdtWithSigner = usdt.connect(signer);
const tx = await usdtWithSigner.transfer(recipientAddress, amount);
await tx.wait();
```
### 2. Ethers.js Integration
```javascript
import { ethers } from 'ethers';
// Connect to provider
const provider = new ethers.JsonRpcProvider('http://192.168.11.250:8545');
// Get contract instance
const tokenRegistryAbi = [...]; // ABI
const tokenRegistryAddress = '0x...';
const registry = new ethers.Contract(tokenRegistryAddress, tokenRegistryAbi, provider);
// Query token info
const tokenInfo = await registry.getTokenInfo(tokenAddress);
const allTokens = await registry.getAllTokens();
const tokenCount = await registry.getTokenCount();
```
### 3. Event Listening
```javascript
// Listen to ValueTransferDeclared events
usdt.on('ValueTransferDeclared', (from, to, value, legalRefHash, event) => {
console.log('Value transfer:', {
from,
to,
value: value.toString(),
legalRefHash,
blockNumber: event.blockNumber
});
});
// Listen to TokenRegistered events
registry.on('TokenRegistered', (tokenAddress, name, symbol, decimals, event) => {
console.log('Token registered:', {
tokenAddress,
name,
symbol,
decimals,
blockNumber: event.blockNumber
});
});
```
---
## Testing Integration
### 1. Foundry Tests
```solidity
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.19;
import "forge-std/Test.sol";
import "../tokens/CompliantUSDT.sol";
import "../utils/TokenRegistry.sol";
contract IntegrationTest is Test {
CompliantUSDT public usdt;
TokenRegistry public registry;
function setUp() public {
usdt = new CompliantUSDT(address(this), address(this));
registry = new TokenRegistry(address(this));
}
function testTokenRegistration() public {
registry.registerToken(
address(usdt),
"Tether USD (Compliant)",
"cUSDT",
6,
false,
address(0)
);
assertTrue(registry.isTokenRegistered(address(usdt)));
assertTrue(registry.isTokenActive(address(usdt)));
}
function testTokenTransfer() public {
address recipient = address(0x123);
uint256 amount = 1000 * 10**6;
usdt.transfer(recipient, amount);
assertEq(usdt.balanceOf(recipient), amount);
}
}
```
---
## Best Practices
### 1. Error Handling
Always check return values and handle errors:
```solidity
function safeTransfer(address token, address to, uint256 amount) external {
IERC20(token).transfer(to, amount);
// Check if transfer was successful
require(IERC20(token).balanceOf(to) >= amount, "Transfer failed");
}
```
### 2. Access Control
Always verify access control:
```solidity
function adminFunction() external {
require(hasRole(DEFAULT_ADMIN_ROLE, msg.sender), "Not admin");
// ...
}
```
### 3. Reentrancy Protection
Use reentrancy guards for state-changing functions:
```solidity
import "@openzeppelin/contracts/security/ReentrancyGuard.sol";
contract MyContract is ReentrancyGuard {
function withdraw() external nonReentrant {
// Safe withdrawal logic
}
}
```
### 4. Event Emission
Always emit events for important state changes:
```solidity
event TokenTransferred(address indexed from, address indexed to, uint256 amount);
function transfer(address to, uint256 amount) external {
// Transfer logic
emit TokenTransferred(msg.sender, to, amount);
}
```
---
## Security Considerations
1. **Always verify contract addresses** before interacting
2. **Check contract state** (paused, active, etc.) before operations
3. **Validate inputs** to prevent unexpected behavior
4. **Use safe math operations** (OpenZeppelin SafeMath or Solidity 0.8+)
5. **Implement access controls** for sensitive operations
6. **Monitor events** for important state changes
7. **Test thoroughly** before deploying to mainnet
---
**Last Updated**: 2025-12-24