Appendix

Roles Matrix

Admin permissions are defined with the following binary values. Roles are defined as the OR of a set of admin roles:

Contract Admin: 000001 (1) Reserve Admin: 000010 (2)
Wallets Admin: 000100 (4) Transfer Admin: 001000 (8) Soft Burn Admin: 010000 (16) Mint Admin: 100000 (32)

Core Admin Roles

Role	Bit Position	Purpose	Key Functions
Contract Admin	000001 (1)	System configuration and emergency controls	Deploy contracts, set max rates, pause operations
Reserve Admin	000010 (2)	Token supply management	mint(), burn(), forceTransferBetween()
Wallets Admin	000100 (4)	Address compliance and group management	AML/KYC, transfer groups, holder management
Transfer Admin	001000 (8)	Transfer rules and payment operations	Group transfers, interest payments, dividend funding
Soft Burn Admin	010000 (16)	Allowance-based burning	softBurn() - burns tokens using allowance mechanism
Mint Admin	100000 (32)	Alternative minting authority	mintTokenType() - specialized minting operations

Soft Burn vs Reserve Admin Burn

Function	Role Required	Mechanism	Use Case
burn()	Reserve Admin	Direct authority	Administrative burns, error corrections
softBurn()	Soft Burn Admin	Requires allowance	DeFi integrations, automated burning protocols

Mint Admin vs Reserve Admin

Function	Role Required	Purpose	Flexibility
mint()	Reserve Admin	Standard minting	Auto token type determination
mintTokenType()	Mint Admin OR Reserve Admin	Specialized minting	Explicit token type control

Key Differences:

• Reserve Admin: Full authority over token supply, suitable for issuer operations
• Soft Burn Admin: Limited to allowance-based burns, suitable for automated protocols
• Mint Admin: Can mint tokens but without broader reserve management powers

Example Role Combinations

Role Integer	Admin Roles	Common Use Case
1	Contract Admin	System configuration only
2	Reserve Admin	Token issuer with full control
16	Soft Burn Admin	DeFi protocol integration
32	Mint Admin	Specialized minting service
18	Reserve Admin + Soft Burn Admin	Comprehensive token management
34	Reserve Admin + Mint Admin	Full minting flexibility
63	All Roles	Development/testing environment

This granular role system allows precise delegation of responsibilities while maintaining security boundaries between different operational concerns.

Post-Deployment Configuration

After smart contract deployment, the system requires comprehensive configuration to enable secure, compliant token operations. The modern configuration process focuses on identity-based compliance and automated rule enforcement.

Phase 1: Administrative Role Assignment

Required Role Assignments:

1. Transfer Admin (8): Configure compliance rules and payment operations
2. Wallets Admin (4): Manage investor identities and compliance status
3. Soft Burn Admin (16): Grant to InterestPayment for principal repayments
4. Mint Admin (32): Grant to PurchaseContract for automated token purchases

Phase 2: Identity Registry & Compliance Setup

Key Configuration Examples:

// Configure RegD 6-month holding period
transferRules.setTransferRule(2, 840, 2, TransferRule({
    lockDurationSeconds: 180 days,
    requiresAmlKyc: true,
    isActive: true
}));

// Configure RegS 1-year offshore holding period
transferRules.setTransferRule(1, 0, 0, TransferRule({
    lockDurationSeconds: 365 days,
    requiresAmlKyc: true,
    isActive: true
}));

Phase 3: Investor Identity Registration

Identity Registration Example:

// Register US accredited investor
uint256[] memory regions = new uint256[](1);
regions[0] = 840; // United States

IdentityInfo memory investorProfile = IdentityInfo({
    regions: regions,
    accreditationType: 2, // Accredited Investor
    amlKycPassed: true,
    lastAmlKycChangeTimestamp: block.timestamp,
    lastAccreditationChangeTimestamp: block.timestamp
});

identityRegistry.setIdentity(investorAddress, investorProfile);

Phase 4: System Integration & Testing

Configuration Checklist

✅ Core System Setup

• Transfer Admin Role: Granted to operational administrator
• Wallets Admin Role: Granted to compliance team
• Soft Burn Admin: Granted to InterestPayment contract
• Mint Admin: Granted to PurchaseContract (if used)

✅ Compliance Configuration

• Token Type Rules: Configured for all investor categories
• Holding Periods: Set per regulatory requirements
• AML/KYC Validity: Duration configured in IdentityRegistry
• Holder Limits: Global and regional limits set (if applicable)

✅ Investor Management

• Identity Profiles: Registered for all initial investors
• AML/KYC Status: Granted with appropriate validity periods
• Accreditation Levels: Assigned per investor sophistication
• Regional Classifications: Multi-jurisdiction support configured

✅ Integration Testing

• Token Minting: Automatic type assignment verified
• Transfer Validation: Holding period restrictions tested
• Payment Systems: Interest and dividend functionality validated
• Purchase Contracts: Automated USDC-to-token conversion tested

Key Operational Benefits

Automated Compliance:

• Token types automatically assigned based on investor identity
• Holding periods enforced without manual intervention
• Real-time validation against current regulations

Simplified Administration:

• Single identity profile replaces multiple permission settings
• Rule-based configuration eliminates repetitive setup
• Clear separation of duties across administrative roles

Enhanced Security:

• Multi-signature recommended for Contract and Reserve Admin roles
• Operational roles isolated from high-value supply management
• Comprehensive audit trail for all administrative actions

Scalability:

• Identity-based system supports unlimited investor profiles
• Rule engine adapts to changing regulatory requirements
• Integration ready for DeFi protocols and institutional systems

Meta Transactions

Meta Transactions are enabled for contracts RestrictedLockupToken.sol, InterestPayment.sol, RestrictedSwap.sol, PurchaseContract.sol, IdentityRegistry.sol, TransferRule.sol. Transactions can be signed off-chain, and then a third party (the relayer) can pay the transaction fees on behalf of the user. This greatly simplifies the user experience, and also allows batching of multiple transactions natively via the forwarder contract. In particular, this simplifies the wallet whitelisting process by allowing the relayer to process multiple transactions on behalf of the Transfer Admin.

A custom ERC2771 forwarder contract has been created to allow for unique, but non-sequential nonce management. The forwarder is based on OpenZeppelin's ERC2771Forwarder.sol contract, except with custom nonce management. This ensures replay protection while also allowing multiple nonces to be utilized within the same batch of transactions without the need to order them.

See contracts/metatx/ERC2771CustomForwarder.sol and contracts/utils/Nonces.sol for more details.

Here is an example flow:

1. The EIP-712 format is used for off-chain signing. The domain specifies the context of the signing, including the contract name, version, chain ID, and verifying contract address (which is the address of the ERC2771 Forwarder). The typed structured data consists of the fields: from (tx signer), to (target token contract), value (amount of coin provided), gas, nonce (unique but not sequential), deadline (timestamp deadline for expiration), and data.

2. The Relayer (any third party payer wallet) must then be provided that signed transaction.

3. The Relayer then executes the meta transaction on behalf of the Transfer Admin signer by calling execute or executeBatch on the ERC2771Forwarder contract with the signed transaction.

4. The forwarder contract will forward the transaction to the target RestrictedLockupToken contract to execute the whitelisting transaction.