smom-dbis-138/docs/bridge/trustless/ACCESS_CONTROL.md

Access Control Documentation

Overview

This document describes the access control structure for all trustless bridge contracts, including roles, permissions, and security considerations.

Access Control Matrix

Lockbox138

Status: Immutable, no admin functions

Function	Access	Notes
depositNative()	Public	Anyone can deposit
depositERC20()	Public	Anyone can deposit
getNonce()	Public	View function
isDepositProcessed()	Public	View function

Security: No admin functions, fully permissionless.

InboxETH

Status: Immutable, no admin functions

Function	Access	Notes
submitClaim()	Public	Relayers submit claims with bond
getClaimStatus()	Public	View function
getClaim()	Public	View function

Security: No admin functions, fully permissionless.

BondManager

Status: Immutable, no admin functions

Function	Access	Notes
postBond()	Public	Relayers post bonds
slashBond()	Public	Only ChallengeManager can call (via external)
releaseBond()	Public	Anyone can release after finalization
getRequiredBond()	Public	View function
getBond()	Public	View function
getTotalBonds()	Public	View function

Security: No admin functions. slashBond() should only be called by ChallengeManager.

ChallengeManager

Status: Immutable, no admin functions

Function	Access	Notes
registerClaim()	Public	Only InboxETH should call
challengeClaim()	Public	Anyone can challenge
finalizeClaim()	Public	Anyone can finalize after window
canFinalize()	Public	View function
getClaim()	Public	View function
getChallenge()	Public	View function

Security: No admin functions. registerClaim() should only be called by InboxETH.

LiquidityPoolETH

Status: Has one admin function (needs access control)

Function	Access	Notes
authorizeRelease()	Public	⚠️ SECURITY ISSUE: Should have access control
provideLiquidity()	Public	Anyone can provide liquidity
depositWETH()	Public	Anyone can deposit WETH
withdrawLiquidity()	Public	LPs can withdraw their liquidity
releaseToRecipient()	Authorized only	Only authorized contracts
addPendingClaim()	Authorized only	Only authorized contracts
removePendingClaim()	Authorized only	Only authorized contracts
getAvailableLiquidity()	Public	View function
getLpShare()	Public	View function
getPoolStats()	Public	View function

Security Issue: authorizeRelease() is public and has no access control. This should be:

• Restricted to owner/multisig, OR
• Only callable during deployment, OR
• Removed if not needed

Recommendation: Add access control to authorizeRelease() or make it only callable during constructor.

SwapRouter

Status: Immutable, no admin functions

Function	Access	Notes
swapToStablecoin()	Public	Anyone can swap
_executeUniswapV3Swap()	Internal	Internal function
_isValidStablecoin()	Internal	Internal function

Security: No admin functions, fully permissionless.

BridgeSwapCoordinator

Status: Immutable, no admin functions

Function	Access	Notes
bridgeAndSwap()	Public	Anyone can execute bridge+swap
canSwap()	Public	View function

Security: No admin functions, fully permissionless.

Access Control Recommendations

1. LiquidityPoolETH.authorizeRelease()

Current State: Public function with no access control

Recommendation: Add owner/multisig access control:

address public owner;

modifier onlyOwner() {
    require(msg.sender == owner, "LiquidityPoolETH: not owner");
    _;
}

function authorizeRelease(address releaser) external onlyOwner {
    require(releaser != address(0), "LiquidityPoolETH: zero address");
    authorizedRelease[releaser] = true;
}

Alternative: If authorization only needed during deployment, remove function and authorize in constructor.

2. ChallengeManager.registerClaim()

Current State: Public function

Recommendation: Add access control to ensure only InboxETH can call:

address public immutable inbox;

modifier onlyInbox() {
    require(msg.sender == inbox, "ChallengeManager: not inbox");
    _;
}

function registerClaim(...) external onlyInbox {
    // ...
}

3. BondManager.slashBond()

Current State: Public function, but should only be called by ChallengeManager

Recommendation: Add access control:

address public immutable challengeManager;

modifier onlyChallengeManager() {
    require(msg.sender == challengeManager, "BondManager: not challenge manager");
    _;
}

function slashBond(...) external onlyChallengeManager returns (...) {
    // ...
}

Role-Based Access Control (Future Enhancement)

Consider implementing a role-based access control system using OpenZeppelin's AccessControl:

import "@openzeppelin/contracts/access/AccessControl.sol";

contract LiquidityPoolETH is ReentrancyGuard, AccessControl {
    bytes32 public constant AUTHORIZER_ROLE = keccak256("AUTHORIZER_ROLE");
    
    constructor(...) {
        _grantRole(DEFAULT_ADMIN_ROLE, msg.sender);
    }
    
    function authorizeRelease(address releaser) external onlyRole(AUTHORIZER_ROLE) {
        // ...
    }
}

Multisig Integration

Transferring Ownership

1. Deploy multisig wallet (Gnosis Safe recommended)
2. Transfer ownership of contracts with admin functions to multisig
3. Update access control roles to multisig address
4. Test multisig operations on testnet

Multisig Operations

See docs/bridge/trustless/MULTISIG_OPERATIONS.md for detailed procedures.

Security Considerations

1. Principle of Least Privilege

• Grant minimum permissions necessary
• Remove unused admin functions
• Use immutable contracts where possible

2. Access Control Review

• Regularly audit access control
• Review all admin functions
• Document all permissions
• Test access control thoroughly

3. Emergency Procedures

• Have emergency pause mechanism
• Document emergency access procedures
• Test emergency procedures regularly
• Maintain backup access methods

Testing Access Control

Test Suite

Create comprehensive access control tests:

// test/bridge/trustless/AccessControl.t.sol
function test_OnlyOwnerCanAuthorizeRelease() public {
    // Test that only owner can authorize release
}

function test_UnauthorizedCannotAuthorizeRelease() public {
    // Test that unauthorized users cannot authorize
}

function test_OnlyInboxCanRegisterClaim() public {
    // Test that only InboxETH can register claims
}

Audit Checklist

• Review all public functions
• Verify admin functions have access control
• Check for missing access control modifiers
• Verify immutable contracts have no admin functions
• Test all access control paths
• Document all roles and permissions
• Review emergency access procedures

References

• Contracts: contracts/bridge/trustless/
• Multisig Operations: docs/bridge/trustless/MULTISIG_OPERATIONS.md
• Security Documentation: docs/bridge/trustless/SECURITY.md