FolioProxy and FolioProxyAdmin

Upgradeable proxy infrastructure for Folio contracts

Overview

The Folio protocol uses an upgradeable proxy pattern with two contracts:

1. FolioProxy: ERC1967-compliant transparent proxy
2. FolioProxyAdmin: Admin contract managing upgrades with version control

This architecture enables protocol upgrades while maintaining state and user balances.

FolioProxyAdmin

The FolioProxyAdmin contract manages upgrades for Folio proxies with built-in version registry integration.

Features

• Version-controlled upgrades
• Ownership-based access control
• Deprecation protection
• Single admin per proxy

Constructor

FolioProxy.sol

constructor(address initialOwner, address _versionRegistry) Ownable(initialOwner)

initialOwner · address

Initial owner of the ProxyAdmin (typically a timelock)

_versionRegistry · address

FolioVersionRegistry address for version validation

Upgrade to Version

Upgrade a proxy to a specific version from the registry.

proxyTarget · address

Address of the FolioProxy to upgrade

versionHash · bytes32

Hash of the version to upgrade to

data · bytes

Calldata to execute after upgrade (typically for re-initialization)

FolioProxy.sol

function upgradeToVersion(
    address proxyTarget,
    bytes32 versionHash,
    bytes memory data
) external onlyOwner

The function will revert if:

• Version is deprecated in the registry
• Version doesn’t exist in the registry
• Caller is not the owner

Version Validation

The upgrade process includes automatic validation:

Upgrade Flow

// 1. Check version is not deprecated
require(!folioRegistry.isDeprecated(versionHash), VersionDeprecated());

// 2. Verify version exists
require(
    address(folioRegistry.deployments(versionHash)) != address(0),
    InvalidVersion()
);

// 3. Get implementation address
address folioImpl = folioRegistry.getImplementationForVersion(versionHash);

// 4. Perform upgrade
ITransparentUpgradeableProxy(proxyTarget).upgradeToAndCall(folioImpl, data);

FolioProxy

The FolioProxy contract is a minimal transparent proxy implementation following ERC1967.

Features

• Transparent proxy pattern
• Immutable admin (cannot change after deployment)
• Restricted admin interface
• Fallback delegation to implementation

Constructor

FolioProxy.sol

constructor(address _logic, address _admin) ERC1967Proxy(_logic, "")

_logic · address

Initial implementation address (Folio contract)

_admin · address

ProxyAdmin address (immutable after deployment)

The admin is stored in the ERC1967 admin slot and cannot be changed after deployment.

Proxy Behavior

The proxy uses a custom _fallback() implementation:

FolioProxy.sol

function _fallback() internal virtual override {
    if (msg.sender == ERC1967Utils.getAdmin()) {
        // Admin can only call upgradeToAndCall
        require(
            msg.sig == ITransparentUpgradeableProxy.upgradeToAndCall.selector,
            ProxyDeniedAdminAccess()
        );

        (address newImplementation, bytes memory data) = abi.decode(
            msg.data[4:],
            (address, bytes)
        );

        ERC1967Utils.upgradeToAndCall(newImplementation, data);
    } else {
        // All other callers are delegated to implementation
        super._fallback();
    }
}

Access Control

Admin · address

Can only call upgradeToAndCall() - no access to implementation functions

Users · address

All calls are delegated to the implementation contract

Upgrade Process

Step-by-Step Upgrade

1. Deploy New Implementation

   Folio newImplementation = new Folio();
   

2. Register Version (via FolioVersionRegistry)

   versionRegistry.registerVersion(newDeployer);
   

3. Prepare Upgrade Data (if needed)

   bytes memory initData = abi.encodeWithSignature(
       "reinitialize(uint256)",
       newVersion
   );
   

4. Execute Upgrade (via ProxyAdmin)

   bytes32 versionHash = keccak256(abi.encodePacked("4.0.0"));
   proxyAdmin.upgradeToVersion(folioProxy, versionHash, initData);
   

Governance Upgrade Example

Timelock Upgrade

// Proposal to upgrade Folio
address[] memory targets = new address[](1);
targets[0] = address(proxyAdmin);

uint256[] memory values = new uint256[](1);
values[0] = 0;

bytes[] memory calldatas = new bytes[](1);
calldatas[0] = abi.encodeWithSignature(
    "upgradeToVersion(address,bytes32,bytes)",
    folioProxy,
    versionHash,
    ""
);

governor.propose(
    targets,
    values,
    calldatas,
    "Upgrade Folio to v4.0.0"
);

Storage Layout

ERC1967 Storage Slots

The proxy follows ERC1967 standard storage slots:

Storage Slots

// Implementation slot
bytes32 IMPLEMENTATION_SLOT = 
    bytes32(uint256(keccak256('eip1967.proxy.implementation')) - 1);

// Admin slot
bytes32 ADMIN_SLOT = 
    bytes32(uint256(keccak256('eip1967.proxy.admin')) - 1);

Never use these slots in the implementation contract to avoid storage collisions.

Security Considerations

Transparent Proxy Pattern

The transparent proxy ensures:

• Admin cannot call implementation functions
• Users cannot call admin functions
• No function selector collisions

Admin Immutability

The admin address is set once during deployment and cannot be changed. This ensures:

• Predictable upgrade permissions
• No admin takeover attacks
• Clear governance structure

Version Control

Integration with FolioVersionRegistry provides:

• Deprecation Protection: Prevents upgrades to deprecated versions
• Version Validation: Ensures implementation exists before upgrade
• Audit Trail: All versions registered on-chain

Events

The proxy emits standard ERC1967 events:

Upgraded · event

Emitted when implementation is upgraded

Parameters:

• implementation - New implementation address

AdminChanged · event

Emitted when admin changes (only during deployment)

Parameters:

• previousAdmin - Previous admin (address(0) initially)
• newAdmin - New admin address

Errors

ProxyDeniedAdminAccess · error

Thrown when admin tries to call non-upgrade functions

VersionDeprecated · error

Thrown when trying to upgrade to a deprecated version

InvalidVersion · error

Thrown when version doesn’t exist in registry

Best Practices

Upgrade Safety

• Always test upgrades on testnet first
• Use initialization functions for new storage variables
• Follow the upgrade pattern for storage layout
• Verify version registration before upgrade proposals

Admin Management

• Use timelock contracts as ProxyAdmin owner
• Implement multi-sig or governance for upgrade decisions
• Monitor version registry for deprecations
• Keep upgrade proposals transparent