Add full monorepo: virtual-banker, backend, frontend, docs, scripts, deployment
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
defiQUG
390
docs/LEGAL_COMPLIANCE_IMPLEMENTATION_GUIDE.md
Normal file
390
docs/LEGAL_COMPLIANCE_IMPLEMENTATION_GUIDE.md
Normal file
@@ -0,0 +1,390 @@
|
||||
# Legal Compliance Implementation Guide
|
||||
|
||||
**Date**: 2025-12-24
|
||||
**Purpose**: Step-by-step guide to implement legal compliance in all contracts
|
||||
|
||||
---
|
||||
|
||||
## 📋 Overview
|
||||
|
||||
This guide provides step-by-step instructions to ensure all smart contracts meet:
|
||||
1. ✅ Hague Conventions on Private Law compliance
|
||||
2. ✅ ISO standards compliance (ISO 20022, ISO 27001, ISO 3166, ISO 8601, ISO 4217)
|
||||
3. ✅ ICC (International Chamber of Commerce) compliance
|
||||
4. ✅ Instruments of Value Transfer classification
|
||||
5. ✅ Exemption from Travel Rules
|
||||
6. ✅ Exemption from Regulatory Compliance bodies
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Implementation Steps
|
||||
|
||||
### Step 1: Deploy Compliance Registry
|
||||
|
||||
```bash
|
||||
cd /home/intlc/projects/smom-dbis-138
|
||||
|
||||
# Set environment variables
|
||||
export COMPLIANCE_REGISTRY_OWNER=0x4A666F96fC8764181194447A7dFdb7d471b301C8
|
||||
|
||||
# Deploy
|
||||
forge script script/DeployComplianceRegistry.s.sol:DeployComplianceRegistry \
|
||||
--rpc-url http://192.168.11.250:8545 \
|
||||
--broadcast \
|
||||
--legacy \
|
||||
--gas-price 20000000000 \
|
||||
-vv
|
||||
```
|
||||
|
||||
**Save the deployed address** to `.env`:
|
||||
```bash
|
||||
COMPLIANCE_REGISTRY_ADDRESS=<deployed_address>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 2: Deploy Compliant Tokens
|
||||
|
||||
#### Deploy Compliant USDT
|
||||
|
||||
```bash
|
||||
# Set environment variables
|
||||
export USDT_OWNER=0x4A666F96fC8764181194447A7dFdb7d471b301C8
|
||||
export LEGAL_NOTICE_ADDRESS=0x4A666F96fC8764181194447A7dFdb7d471b301C8
|
||||
export USDT_INITIAL_SUPPLY=0 # 0 = no initial supply
|
||||
|
||||
# Deploy
|
||||
forge script script/DeployCompliantUSDT.s.sol:DeployCompliantUSDT \
|
||||
--rpc-url http://192.168.11.250:8545 \
|
||||
--broadcast \
|
||||
--legacy \
|
||||
--gas-price 20000000000 \
|
||||
--via-ir \
|
||||
-vv
|
||||
```
|
||||
|
||||
#### Deploy Compliant USDC
|
||||
|
||||
```bash
|
||||
# Set environment variables
|
||||
export USDC_OWNER=0x4A666F96fC8764181194447A7dFdb7d471b301C8
|
||||
export LEGAL_NOTICE_ADDRESS=0x4A666F96fC8764181194447A7dFdb7d471b301C8
|
||||
export USDC_INITIAL_SUPPLY=0
|
||||
|
||||
# Deploy
|
||||
forge script script/DeployCompliantUSDC.s.sol:DeployCompliantUSDC \
|
||||
--rpc-url http://192.168.11.250:8545 \
|
||||
--broadcast \
|
||||
--legacy \
|
||||
--gas-price 20000000000 \
|
||||
--via-ir \
|
||||
-vv
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 3: Register Contracts in Compliance Registry
|
||||
|
||||
After deploying tokens, register them in the compliance registry:
|
||||
|
||||
```bash
|
||||
# Set variables
|
||||
COMPLIANCE_REGISTRY=<compliance_registry_address>
|
||||
USDT_ADDRESS=<usdt_address>
|
||||
USDC_ADDRESS=<usdc_address>
|
||||
LEGAL_NOTICE_ADDRESS=0x4A666F96fC8764181194447A7dFdb7d471b301C8
|
||||
JURISDICTION="[Your Jurisdiction]" # e.g., "Switzerland", "Singapore", etc.
|
||||
|
||||
# Register USDT
|
||||
cast send $COMPLIANCE_REGISTRY \
|
||||
"registerContract(address,(bool,bool,bool,bool,bool,string,address,uint256,string))" \
|
||||
$USDT_ADDRESS \
|
||||
true true true true true \
|
||||
"$JURISDICTION" \
|
||||
$LEGAL_NOTICE_ADDRESS \
|
||||
0 \
|
||||
"Value Transfer Instrument" \
|
||||
--rpc-url http://192.168.11.250:8545 \
|
||||
--private-key $PRIVATE_KEY
|
||||
|
||||
# Register USDC
|
||||
cast send $COMPLIANCE_REGISTRY \
|
||||
"registerContract(address,(bool,bool,bool,bool,bool,string,address,uint256,string))" \
|
||||
$USDC_ADDRESS \
|
||||
true true true true true \
|
||||
"$JURISDICTION" \
|
||||
$LEGAL_NOTICE_ADDRESS \
|
||||
0 \
|
||||
"Value Transfer Instrument" \
|
||||
--rpc-url http://192.168.11.250:8545 \
|
||||
--private-key $PRIVATE_KEY
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 4: Update Existing Contracts
|
||||
|
||||
#### For Token Contracts (USDT, USDC, Governance Token)
|
||||
|
||||
**Option A: Inherit from LegallyCompliantBase**
|
||||
|
||||
```solidity
|
||||
import "../compliance/LegallyCompliantBase.sol";
|
||||
|
||||
contract YourToken is ERC20, Ownable, Pausable, LegallyCompliantBase {
|
||||
constructor(
|
||||
address owner,
|
||||
address legalNoticeAddress
|
||||
)
|
||||
ERC20("Token Name", "SYMBOL")
|
||||
LegallyCompliantBase(legalNoticeAddress)
|
||||
{
|
||||
_transferOwnership(owner);
|
||||
}
|
||||
|
||||
function transfer(address to, uint256 amount)
|
||||
public
|
||||
override
|
||||
whenNotPaused
|
||||
returns (bool)
|
||||
{
|
||||
bool result = super.transfer(to, amount);
|
||||
if (result) {
|
||||
string memory legalRef = _generateLegalReference(msg.sender, to, amount);
|
||||
emitCompliantValueTransfer(msg.sender, to, amount, legalRef, bytes32(0));
|
||||
}
|
||||
return result;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Option B: Add Compliance Declarations**
|
||||
|
||||
Add to existing contracts:
|
||||
```solidity
|
||||
// Legal Framework
|
||||
string public constant LEGAL_JURISDICTION = "[Jurisdiction]";
|
||||
string public constant TRAVEL_RULES_EXEMPT = "Private value transfer instrument";
|
||||
string public constant REGULATORY_EXEMPT = "Private value transfer instrument";
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 5: Update Bridge Contracts
|
||||
|
||||
#### For CCIPWETH9Bridge and CCIPWETH10Bridge
|
||||
|
||||
Add compliance features:
|
||||
|
||||
```solidity
|
||||
import "../compliance/LegallyCompliantBase.sol";
|
||||
|
||||
contract CCIPWETH9Bridge is LegallyCompliantBase {
|
||||
// ... existing code ...
|
||||
|
||||
function _bridge(
|
||||
address to,
|
||||
uint256 amount,
|
||||
uint64 destinationChainSelector
|
||||
) internal {
|
||||
// ... existing bridge logic ...
|
||||
|
||||
// Emit compliant value transfer
|
||||
string memory legalRef = _generateLegalReference(msg.sender, to, amount);
|
||||
emitCompliantValueTransfer(
|
||||
msg.sender,
|
||||
to,
|
||||
amount,
|
||||
legalRef,
|
||||
bytes32(0)
|
||||
);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 6: Update eMoney Contracts
|
||||
|
||||
#### For ISO20022Router
|
||||
|
||||
The contract already has ISO 20022 support. Add:
|
||||
|
||||
```solidity
|
||||
import "../compliance/LegallyCompliantBase.sol";
|
||||
|
||||
contract ISO20022Router is IISO20022Router, AccessControl, LegallyCompliantBase {
|
||||
// ... existing code ...
|
||||
|
||||
function submitOutbound(CanonicalMessage calldata m)
|
||||
external
|
||||
override
|
||||
onlyRole(RAIL_OPERATOR_ROLE)
|
||||
returns (uint256 triggerId)
|
||||
{
|
||||
// ... existing logic ...
|
||||
|
||||
// Emit compliant value transfer with ISO 20022 message ID
|
||||
emitCompliantValueTransfer(
|
||||
address(0), // Will be resolved from message
|
||||
address(0), // Will be resolved from message
|
||||
m.amount,
|
||||
string(abi.encodePacked("ISO20022-", _toHexString(m.instructionId))),
|
||||
m.instructionId
|
||||
);
|
||||
|
||||
return triggerId;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📋 Compliance Checklist
|
||||
|
||||
### For Each Contract
|
||||
|
||||
#### Legal Framework
|
||||
- [ ] Inherit from `LegallyCompliantBase` OR add compliance declarations
|
||||
- [ ] Set `LEGAL_JURISDICTION` constant
|
||||
- [ ] Set `LEGAL_NOTICE_ADDRESS` in constructor
|
||||
- [ ] Emit `ValueTransfer` events with legal references
|
||||
- [ ] Emit `LegalNotice` events for important actions
|
||||
|
||||
#### ISO Standards
|
||||
- [ ] ISO 20022 message format (if applicable)
|
||||
- [ ] ISO 8601 timestamps (use `block.timestamp`)
|
||||
- [ ] ISO 4217 currency codes (if applicable)
|
||||
- [ ] ISO 27001 security controls (access control, pausable)
|
||||
|
||||
#### ICC Compliance
|
||||
- [ ] ICC rules version declared
|
||||
- [ ] ICC-compliant event emissions
|
||||
|
||||
#### Value Transfer Instrument
|
||||
- [ ] `INSTRUMENT_TYPE` declared
|
||||
- [ ] `LEGAL_STATUS` declared
|
||||
- [ ] Transfer functions emit compliant events
|
||||
- [ ] Legal references generated for transfers
|
||||
|
||||
#### Travel Rules Exemption
|
||||
- [ ] `TRAVEL_RULES_EXEMPT` declaration
|
||||
- [ ] No KYC/AML requirements
|
||||
- [ ] No originator/beneficiary data collection
|
||||
- [ ] No transaction monitoring
|
||||
- [ ] No reporting mechanisms
|
||||
|
||||
#### Regulatory Compliance Exemption
|
||||
- [ ] `REGULATORY_EXEMPT` declaration
|
||||
- [ ] `NOT_MONEY_TRANSMISSION` declaration
|
||||
- [ ] `NOT_PAYMENT_SERVICE` declaration
|
||||
- [ ] Private instrument classification
|
||||
|
||||
---
|
||||
|
||||
## 🔍 Verification
|
||||
|
||||
### Verify Compliance Status
|
||||
|
||||
```bash
|
||||
# Check if contract is registered
|
||||
cast call $COMPLIANCE_REGISTRY \
|
||||
"complianceStatus(address)" \
|
||||
$TOKEN_ADDRESS \
|
||||
--rpc-url http://192.168.11.250:8545
|
||||
|
||||
# Check if fully compliant
|
||||
cast call $COMPLIANCE_REGISTRY \
|
||||
"isFullyCompliant(address)" \
|
||||
$TOKEN_ADDRESS \
|
||||
--rpc-url http://192.168.11.250:8545
|
||||
```
|
||||
|
||||
### Verify Contract Constants
|
||||
|
||||
```bash
|
||||
# Check legal jurisdiction
|
||||
cast call $TOKEN_ADDRESS "LEGAL_JURISDICTION()" --rpc-url http://192.168.11.250:8545
|
||||
|
||||
# Check exemption declarations
|
||||
cast call $TOKEN_ADDRESS "TRAVEL_RULES_EXEMPT()" --rpc-url http://192.168.11.250:8545
|
||||
cast call $TOKEN_ADDRESS "REGULATORY_EXEMPT()" --rpc-url http://192.168.11.250:8545
|
||||
|
||||
# Check instrument type
|
||||
cast call $TOKEN_ADDRESS "INSTRUMENT_TYPE()" --rpc-url http://192.168.11.250:8545
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📄 Documentation Requirements
|
||||
|
||||
### Contract-Level Documentation
|
||||
|
||||
Each contract must document:
|
||||
1. **Legal Framework**: Hague Conventions, ISO, ICC compliance
|
||||
2. **Jurisdiction**: Applicable law and jurisdiction
|
||||
3. **Exemption Basis**: Why exempt from Travel Rules and regulatory compliance
|
||||
4. **Instrument Classification**: Value transfer instrument classification
|
||||
|
||||
### System-Level Documentation
|
||||
|
||||
1. **Compliance Policy**: Overall compliance approach
|
||||
2. **Legal Structure**: Legal entity structure (if applicable)
|
||||
3. **Exemption Justification**: Legal basis for exemptions
|
||||
4. **Regulatory Analysis**: Analysis of regulatory status
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ Important Legal Notes
|
||||
|
||||
### Legal Review Required
|
||||
|
||||
**CRITICAL**: This implementation provides technical framework. You must:
|
||||
|
||||
1. **Consult Legal Counsel**:
|
||||
- Hague Conventions expert
|
||||
- ISO standards compliance expert
|
||||
- ICC regulations expert
|
||||
- Financial services lawyer
|
||||
- Regulatory compliance lawyer
|
||||
|
||||
2. **Jurisdiction-Specific Review**:
|
||||
- Verify jurisdiction-specific requirements
|
||||
- Confirm Travel Rules exemption eligibility
|
||||
- Confirm regulatory exemption eligibility
|
||||
- Verify legal instrument classification
|
||||
|
||||
3. **Legal Opinions**:
|
||||
- Obtain legal opinion on contract classification
|
||||
- Obtain legal opinion on exemption eligibility
|
||||
- Obtain legal opinion on jurisdiction requirements
|
||||
|
||||
4. **Regulatory Verification**:
|
||||
- Verify with local regulatory bodies
|
||||
- Confirm exemption status
|
||||
- Document regulatory position
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Next Steps
|
||||
|
||||
1. **Legal Consultation**: Engage legal counsel
|
||||
2. **Jurisdiction Selection**: Choose appropriate jurisdiction
|
||||
3. **Contract Deployment**: Deploy compliant contracts
|
||||
4. **Registry Registration**: Register all contracts
|
||||
5. **Documentation**: Complete legal documentation
|
||||
6. **Verification**: Verify compliance status
|
||||
|
||||
---
|
||||
|
||||
## 📚 References
|
||||
|
||||
- **Legal Compliance Requirements**: `docs/LEGAL_COMPLIANCE_REQUIREMENTS.md`
|
||||
- **Compliant Contracts**: `contracts/compliance/` and `contracts/tokens/Compliant*.sol`
|
||||
- **Deployment Scripts**: `script/DeployCompliant*.s.sol`
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-12-24
|
||||
**Status**: Implementation Guide - Legal Review Required
|
||||
|
||||
Reference in New Issue
Block a user