How d-democrazy/btcxfactory_selfcustodial works
Main Components
• User’s Smart Contract Wallets – These are external entities that lock collateral, trigger minting, and initiate burning.
• BTCX Token Contract (BTCX.sol) – An ordinary ERC20 token (inheriting from OpenZeppelin contracts) that represents the stablecoin (BTCX) and whose supply/circulation is centrally controlled.
• CollateralManager – Representing a proxy pattern (with Implementation, Library, and Proxy files) that holds the list of allowed collateral contract addresses. This contract validates that any collateral locked is on the allowed list.
• WalletRegistry – Another proxy-based component which tracks the lock/unlock state of each user’s smart contract wallet. By performing an extcodehash check, it ensures that the wallet includes the WalletRegistry logic.
• BTCXFactory – The central ordinary contract that ties everything together. When a user requests a mint (or burn), BTCXFactory interacts with BTCX, CollateralManager, and WalletRegistry to validate that all conditions—such as collateral ratios, min/max thresholds, and available token supply—are met.
• Deployment and Support Scripts/Configurations – Foundry configuration (foundry.toml) and deployment scripts (in the “script” directory) that drive the deployment process. These are important for operational understanding but are peripheral to the core runtime architecture.
Relationships and Interactions
• The user’s smart contract wallet initially locks an allowed collateral (as per the CollateralManager’s list) and automatically broadcasts its “lock” state to the WalletRegistry.
• When invoking the mint function on BTCXFactory:
– BTCXFactory checks BTCX.sol for total supply and circulating supply.
– It queries CollateralManager to verify that the collateral being locked is approved.
– It validates the user’s overall collateral locking status via WalletRegistry (which also enforces minimum and maximum thresholds).
– Provided all conditions are met, BTCXFactory initiates minting (in line with the 1:100 ratio) and directs the BTCX Token Contract to mint tokens, updating the user’s wallet balance.
• For burning, the flow reverses: the wallet submits a burn request through BTCXFactory, which again consults the other contracts to ensure that burning will unlock the corresponding collateral.
Architectural Patterns and Design Principles
• Proxy Pattern: Notice that for each main service (CollateralManager, WalletRegistry, BTCXFactory, and BTCX), there are separate implementation and proxy contracts. This enables upgradeability while preserving state and ensuring contract logic can be updated.
• Separation of Concerns: Each contract focuses on specific responsibilities (e.g., CollateralManager for allowed addresses, WalletRegistry for state tracking), and BTCXFactory acts as the orchestrator for minting and burning.
• Data Flow Validation: BTCXFactory does not operate in isolation but always checks the state consistency across BTCX, CollateralManager, and WalletRegistry. The system design must show these validation loops clearly.