Initial project setup: Add contracts, API definitions, tests, and documentation

- Add Foundry project configuration (foundry.toml, foundry.lock)
- Add Solidity contracts (TokenFactory138, BridgeVault138, ComplianceRegistry, etc.)
- Add API definitions (OpenAPI, GraphQL, gRPC, AsyncAPI)
- Add comprehensive test suite (unit, integration, fuzz, invariants)
- Add API services (REST, GraphQL, orchestrator, packet service)
- Add documentation (ISO20022 mapping, runbooks, adapter guides)
- Add development tools (RBC tool, Swagger UI, mock server)
- Update OpenZeppelin submodules to v5.0.0
This commit is contained in:
defiQUG
2025-12-12 10:59:41 -08:00
parent 26b5aaf932
commit 651ff4f7eb
281 changed files with 24813 additions and 2 deletions

View File

@@ -0,0 +1,144 @@
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;
import "forge-std/Test.sol";
import "../../src/DebtRegistry.sol";
import "../../src/interfaces/IDebtRegistry.sol";
contract DebtRegistryFuzz is Test {
DebtRegistry public registry;
address public admin;
address public debtAuthority;
struct LienState {
uint256 id;
address debtor;
uint256 amount;
bool active;
}
LienState[] public lienStates;
function setUp() public {
admin = address(0x1);
debtAuthority = address(0x2);
registry = new DebtRegistry(admin);
vm.startPrank(admin);
registry.grantRole(registry.DEBT_AUTHORITY_ROLE(), debtAuthority);
vm.stopPrank();
}
function testFuzz_placeAndReleaseLiens(
address debtor,
uint256 amount,
uint64 expiry
) public {
vm.assume(debtor != address(0));
vm.assume(amount > 0 && amount < type(uint128).max);
uint256 initialEncumbrance = registry.activeLienAmount(debtor);
uint256 initialCount = registry.activeLienCount(debtor);
vm.prank(debtAuthority);
uint256 lienId = registry.placeLien(debtor, amount, expiry, 1, bytes32(0));
assertEq(registry.activeLienAmount(debtor), initialEncumbrance + amount);
assertEq(registry.activeLienCount(debtor), initialCount + 1);
vm.prank(debtAuthority);
registry.releaseLien(lienId);
assertEq(registry.activeLienAmount(debtor), initialEncumbrance);
assertEq(registry.activeLienCount(debtor), initialCount);
}
function testFuzz_reduceLien(uint256 initialAmount, uint256 reduceBy) public {
vm.assume(initialAmount > 0 && initialAmount < type(uint128).max);
vm.assume(reduceBy <= initialAmount);
address debtor = address(0x100);
vm.prank(debtAuthority);
uint256 lienId = registry.placeLien(debtor, initialAmount, 0, 1, bytes32(0));
uint256 expectedEncumbrance = initialAmount - reduceBy;
vm.prank(debtAuthority);
registry.reduceLien(lienId, reduceBy);
assertEq(registry.activeLienAmount(debtor), expectedEncumbrance);
IDebtRegistry.Lien memory lien = registry.getLien(lienId);
assertEq(lien.amount, expectedEncumbrance);
assertTrue(lien.active);
}
function testFuzz_reduceLien_exceedsAmount(uint256 initialAmount, uint256 reduceBy) public {
vm.assume(initialAmount > 0 && initialAmount < type(uint128).max);
vm.assume(reduceBy > initialAmount);
address debtor = address(0x100);
vm.prank(debtAuthority);
uint256 lienId = registry.placeLien(debtor, initialAmount, 0, 1, bytes32(0));
vm.prank(debtAuthority);
vm.expectRevert("DebtRegistry: reduceBy exceeds amount");
registry.reduceLien(lienId, reduceBy);
}
function testFuzz_multipleLiens(
address debtor,
uint256[5] memory amounts
) public {
vm.assume(debtor != address(0));
uint256 totalExpected = 0;
uint256[] memory lienIds = new uint256[](5);
bool[] memory placed = new bool[](5);
for (uint256 i = 0; i < 5; i++) {
if (amounts[i] > 0 && amounts[i] < type(uint128).max) {
vm.prank(debtAuthority);
lienIds[i] = registry.placeLien(debtor, amounts[i], 0, 1, bytes32(0));
totalExpected += amounts[i];
placed[i] = true;
}
}
assertEq(registry.activeLienAmount(debtor), totalExpected);
// Release all liens that were placed
for (uint256 i = 0; i < 5; i++) {
if (placed[i]) {
vm.prank(debtAuthority);
registry.releaseLien(lienIds[i]);
}
}
assertEq(registry.activeLienAmount(debtor), 0);
assertEq(registry.activeLienCount(debtor), 0);
}
function testFuzz_encumbranceAlwaysNonNegative(
address debtor,
uint256 amount,
uint256 reduceBy
) public {
vm.assume(debtor != address(0));
vm.assume(amount > 0 && amount < type(uint128).max);
vm.assume(reduceBy <= amount);
vm.prank(debtAuthority);
uint256 lienId = registry.placeLien(debtor, amount, 0, 1, bytes32(0));
vm.prank(debtAuthority);
registry.reduceLien(lienId, reduceBy);
uint256 encumbrance = registry.activeLienAmount(debtor);
assertGe(encumbrance, 0); // Should never underflow
}
}

View File

@@ -0,0 +1,161 @@
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;
import "forge-std/Test.sol";
import "../../src/RailTriggerRegistry.sol";
import "../../src/interfaces/IRailTriggerRegistry.sol";
import "../../src/libraries/RailTypes.sol";
contract RailTriggerFuzzTest is Test {
RailTriggerRegistry public registry;
address public admin;
address public railOperator;
address public railAdapter;
address public token;
function setUp() public {
admin = address(0x1);
railOperator = address(0x2);
railAdapter = address(0x3);
token = address(0x100);
registry = new RailTriggerRegistry(admin);
vm.startPrank(admin);
registry.grantRole(registry.RAIL_OPERATOR_ROLE(), railOperator);
registry.grantRole(registry.RAIL_ADAPTER_ROLE(), railAdapter);
vm.stopPrank();
}
function testFuzz_createTrigger(
uint8 railValue,
bytes32 msgType,
bytes32 accountRefId,
bytes32 instructionId,
uint256 amount
) public {
// Bound rail value to valid enum
RailTypes.Rail rail = RailTypes.Rail(railValue % 4);
// Ensure non-zero values
vm.assume(accountRefId != bytes32(0));
vm.assume(instructionId != bytes32(0));
vm.assume(amount > 0);
vm.assume(amount < type(uint128).max); // Reasonable bound
IRailTriggerRegistry.Trigger memory t = IRailTriggerRegistry.Trigger({
id: 0,
rail: rail,
msgType: msgType,
accountRefId: accountRefId,
walletRefId: bytes32(0),
token: token,
amount: amount,
currencyCode: keccak256("USD"),
instructionId: instructionId,
state: RailTypes.State.CREATED,
createdAt: 0,
updatedAt: 0
});
vm.prank(railOperator);
uint256 id = registry.createTrigger(t);
IRailTriggerRegistry.Trigger memory retrieved = registry.getTrigger(id);
assertEq(uint8(retrieved.rail), uint8(rail));
assertEq(retrieved.msgType, msgType);
assertEq(retrieved.amount, amount);
assertEq(retrieved.instructionId, instructionId);
assertTrue(registry.instructionIdExists(instructionId));
}
function testFuzz_stateTransitions(
bytes32 instructionId,
uint8 targetStateValue
) public {
vm.assume(instructionId != bytes32(0));
// Create trigger
IRailTriggerRegistry.Trigger memory t = IRailTriggerRegistry.Trigger({
id: 0,
rail: RailTypes.Rail.SWIFT,
msgType: keccak256("pacs.008"),
accountRefId: keccak256("account1"),
walletRefId: bytes32(0),
token: token,
amount: 1000,
currencyCode: keccak256("USD"),
instructionId: instructionId,
state: RailTypes.State.CREATED,
createdAt: 0,
updatedAt: 0
});
vm.prank(railOperator);
uint256 id = registry.createTrigger(t);
// Try valid transitions
RailTypes.State targetState = RailTypes.State(targetStateValue % 8);
// Valid transitions from CREATED
if (targetState == RailTypes.State.VALIDATED ||
targetState == RailTypes.State.REJECTED ||
targetState == RailTypes.State.CANCELLED) {
vm.prank(railAdapter);
registry.updateState(id, targetState, bytes32(0));
IRailTriggerRegistry.Trigger memory trigger = registry.getTrigger(id);
assertEq(uint8(trigger.state), uint8(targetState));
}
}
function testFuzz_duplicateInstructionId(
bytes32 instructionId,
bytes32 accountRefId1,
bytes32 accountRefId2
) public {
vm.assume(instructionId != bytes32(0));
vm.assume(accountRefId1 != bytes32(0));
vm.assume(accountRefId2 != bytes32(0));
vm.assume(accountRefId1 != accountRefId2);
IRailTriggerRegistry.Trigger memory t1 = IRailTriggerRegistry.Trigger({
id: 0,
rail: RailTypes.Rail.SWIFT,
msgType: keccak256("pacs.008"),
accountRefId: accountRefId1,
walletRefId: bytes32(0),
token: token,
amount: 1000,
currencyCode: keccak256("USD"),
instructionId: instructionId,
state: RailTypes.State.CREATED,
createdAt: 0,
updatedAt: 0
});
vm.prank(railOperator);
registry.createTrigger(t1);
// Try to create another trigger with same instructionId
IRailTriggerRegistry.Trigger memory t2 = IRailTriggerRegistry.Trigger({
id: 0,
rail: RailTypes.Rail.FEDWIRE,
msgType: keccak256("pain.001"),
accountRefId: accountRefId2,
walletRefId: bytes32(0),
token: token,
amount: 2000,
currencyCode: keccak256("EUR"),
instructionId: instructionId, // Same instructionId
state: RailTypes.State.CREATED,
createdAt: 0,
updatedAt: 0
});
vm.prank(railOperator);
vm.expectRevert("RailTriggerRegistry: duplicate instructionId");
registry.createTrigger(t2);
}
}

View File

@@ -0,0 +1,132 @@
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;
import "forge-std/Test.sol";
import "../../src/RailEscrowVault.sol";
import "../../src/interfaces/IRailEscrowVault.sol";
import "../../src/libraries/RailTypes.sol";
import "@openzeppelin/contracts/token/ERC20/ERC20.sol";
contract MockERC20 is ERC20 {
constructor() ERC20("Mock Token", "MOCK") {
_mint(msg.sender, type(uint256).max / 2); // Avoid overflow
}
function mint(address to, uint256 amount) external {
_mint(to, amount);
}
}
contract SettlementFuzzTest is Test {
RailEscrowVault public vault;
MockERC20 public token;
address public admin;
address public settlementOperator;
address public user;
function setUp() public {
admin = address(0x1);
settlementOperator = address(0x2);
user = address(0x10);
vault = new RailEscrowVault(admin);
token = new MockERC20();
vm.startPrank(admin);
vault.grantRole(vault.SETTLEMENT_OPERATOR_ROLE(), settlementOperator);
vm.stopPrank();
}
function testFuzz_lockAndRelease(
uint256 amount,
uint256 triggerId
) public {
vm.assume(amount > 0);
vm.assume(amount < type(uint128).max);
vm.assume(triggerId > 0);
vm.assume(triggerId < type(uint128).max);
// Give user tokens
token.mint(user, amount);
vm.startPrank(user);
token.approve(address(vault), amount);
vm.stopPrank();
// Lock
vm.prank(settlementOperator);
vault.lock(address(token), user, amount, triggerId, RailTypes.Rail.SWIFT);
assertEq(vault.getEscrowAmount(address(token), triggerId), amount);
assertEq(vault.getTotalEscrow(address(token)), amount);
// Release
address recipient = address(0x20);
uint256 recipientBalanceBefore = token.balanceOf(recipient);
vm.prank(settlementOperator);
vault.release(address(token), recipient, amount, triggerId);
assertEq(vault.getEscrowAmount(address(token), triggerId), 0);
assertEq(vault.getTotalEscrow(address(token)), 0);
assertEq(token.balanceOf(recipient), recipientBalanceBefore + amount);
}
function testFuzz_multipleLocks(
uint256 amount1,
uint256 amount2,
uint256 triggerId1,
uint256 triggerId2
) public {
vm.assume(amount1 > 0 && amount2 > 0);
vm.assume(amount1 < type(uint128).max / 2);
vm.assume(amount2 < type(uint128).max / 2);
vm.assume(triggerId1 > 0 && triggerId2 > 0);
vm.assume(triggerId1 != triggerId2);
vm.assume(triggerId1 < type(uint128).max && triggerId2 < type(uint128).max);
uint256 totalAmount = amount1 + amount2;
token.mint(user, totalAmount);
vm.startPrank(user);
token.approve(address(vault), totalAmount);
vm.stopPrank();
// Lock first amount
vm.prank(settlementOperator);
vault.lock(address(token), user, amount1, triggerId1, RailTypes.Rail.SWIFT);
// Lock second amount
vm.prank(settlementOperator);
vault.lock(address(token), user, amount2, triggerId2, RailTypes.Rail.FEDWIRE);
assertEq(vault.getEscrowAmount(address(token), triggerId1), amount1);
assertEq(vault.getEscrowAmount(address(token), triggerId2), amount2);
assertEq(vault.getTotalEscrow(address(token)), totalAmount);
}
function testFuzz_releaseInsufficient(
uint256 lockAmount,
uint256 releaseAmount,
uint256 triggerId
) public {
vm.assume(lockAmount > 0);
vm.assume(releaseAmount > lockAmount); // Try to release more than locked
vm.assume(lockAmount < type(uint128).max);
vm.assume(triggerId > 0);
token.mint(user, lockAmount);
vm.startPrank(user);
token.approve(address(vault), lockAmount);
vm.stopPrank();
vm.prank(settlementOperator);
vault.lock(address(token), user, lockAmount, triggerId, RailTypes.Rail.SWIFT);
vm.prank(settlementOperator);
vm.expectRevert("RailEscrowVault: insufficient escrow");
vault.release(address(token), address(0x20), releaseAmount, triggerId);
}
}

View File

@@ -0,0 +1,162 @@
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;
import "forge-std/Test.sol";
import "../../src/eMoneyToken.sol";
import "../../src/PolicyManager.sol";
import "../../src/ComplianceRegistry.sol";
import "../../src/DebtRegistry.sol";
import "../../src/errors/TokenErrors.sol";
import "../../src/libraries/ReasonCodes.sol";
import "@openzeppelin/contracts/proxy/ERC1967/ERC1967Proxy.sol";
contract TransferFuzz is Test {
eMoneyToken public token;
PolicyManager public policyManager;
ComplianceRegistry public complianceRegistry;
DebtRegistry public debtRegistry;
address public admin;
address public issuer;
address public user1;
address public user2;
function setUp() public {
admin = address(0x1);
issuer = address(0x2);
user1 = address(0x10);
user2 = address(0x20);
complianceRegistry = new ComplianceRegistry(admin);
debtRegistry = new DebtRegistry(admin);
policyManager = new PolicyManager(admin, address(complianceRegistry), address(debtRegistry));
eMoneyToken implementation = new eMoneyToken();
bytes memory initData = abi.encodeWithSelector(
eMoneyToken.initialize.selector,
"Test Token",
"TEST",
18,
issuer,
address(policyManager),
address(debtRegistry),
address(complianceRegistry)
);
ERC1967Proxy proxy = new ERC1967Proxy(address(implementation), initData);
token = eMoneyToken(address(proxy));
vm.startPrank(admin);
policyManager.grantRole(policyManager.POLICY_OPERATOR_ROLE(), admin);
policyManager.setLienMode(address(token), 2); // Encumbered mode
complianceRegistry.grantRole(complianceRegistry.COMPLIANCE_ROLE(), admin);
complianceRegistry.setCompliance(user1, true, 1, bytes32(0));
complianceRegistry.setCompliance(user2, true, 1, bytes32(0));
debtRegistry.grantRole(debtRegistry.DEBT_AUTHORITY_ROLE(), admin);
vm.stopPrank();
}
function testFuzz_transferWithLien(
uint256 mintAmount,
uint256 lienAmount,
uint256 transferAmount
) public {
// Bound inputs to reasonable ranges
mintAmount = bound(mintAmount, 1, type(uint128).max);
lienAmount = bound(lienAmount, 0, mintAmount);
transferAmount = bound(transferAmount, 0, mintAmount);
// Mint to user1
vm.prank(issuer);
token.mint(user1, mintAmount, ReasonCodes.OK);
// Place lien
if (lienAmount > 0) {
vm.prank(admin);
debtRegistry.placeLien(user1, lienAmount, 0, 1, ReasonCodes.LIEN_BLOCK);
}
uint256 freeBalance = token.freeBalanceOf(user1);
bool shouldSucceed = transferAmount <= freeBalance && transferAmount > 0;
if (shouldSucceed) {
vm.prank(user1);
token.transfer(user2, transferAmount);
assertEq(token.balanceOf(user1), mintAmount - transferAmount);
assertEq(token.balanceOf(user2), transferAmount);
} else if (transferAmount > freeBalance && lienAmount > 0) {
// Should fail with insufficient free balance
vm.expectRevert();
vm.prank(user1);
token.transfer(user2, transferAmount);
}
}
function testFuzz_transferWithMultipleLiens(
uint256 mintAmount,
uint256[3] memory lienAmounts,
uint256 transferAmount
) public {
mintAmount = bound(mintAmount, 1000, type(uint128).max);
transferAmount = bound(transferAmount, 0, mintAmount);
// Bound lien amounts
for (uint256 i = 0; i < 3; i++) {
lienAmounts[i] = bound(lienAmounts[i], 0, mintAmount / 3);
}
// Mint to user1
vm.prank(issuer);
token.mint(user1, mintAmount, ReasonCodes.OK);
// Place multiple liens
uint256 totalLienAmount = 0;
for (uint256 i = 0; i < 3; i++) {
if (lienAmounts[i] > 0) {
vm.prank(admin);
debtRegistry.placeLien(user1, lienAmounts[i], 0, 1, ReasonCodes.LIEN_BLOCK);
totalLienAmount += lienAmounts[i];
}
}
uint256 freeBalance = mintAmount > totalLienAmount ? mintAmount - totalLienAmount : 0;
bool shouldSucceed = transferAmount <= freeBalance && transferAmount > 0;
if (shouldSucceed) {
vm.prank(user1);
token.transfer(user2, transferAmount);
assertEq(token.balanceOf(user1), mintAmount - transferAmount);
} else if (transferAmount > freeBalance && totalLienAmount > 0) {
vm.expectRevert();
vm.prank(user1);
token.transfer(user2, transferAmount);
}
}
function testFuzz_freeBalanceCalculation(
uint256 balance,
uint256 encumbrance
) public {
balance = bound(balance, 0, type(uint128).max);
encumbrance = bound(encumbrance, 0, type(uint128).max);
if (balance > 0) {
vm.prank(issuer);
token.mint(user1, balance, ReasonCodes.OK);
}
if (encumbrance > 0) {
vm.prank(admin);
debtRegistry.placeLien(user1, encumbrance, 0, 1, ReasonCodes.LIEN_BLOCK);
}
uint256 freeBalance = token.freeBalanceOf(user1);
uint256 expectedFreeBalance = balance > encumbrance ? balance - encumbrance : 0;
assertEq(freeBalance, expectedFreeBalance, "Free balance calculation incorrect");
}
}