utils.sol

📚 Documentation

Contents

• DepositContractLike
• IAdministrable
• ICub
• IDepositor
• IFixable
• IFixer
• IHatcher
• INFT
• IProxyFactory

DepositContractLike

Git Source

Functions

deposit

function deposit(
    bytes calldata pubkey,
    bytes calldata withdrawalCredentials,
    bytes calldata signature,
    bytes32 depositDataRoot
) external payable;

Events

DepositEvent

event DepositEvent(bytes pubkey, bytes withdrawal_credentials, bytes amount, bytes signature, bytes index);

IAdministrable

Git Source

Author: mortimr @ Kiln

This contract provides all the utilities to handle the administration and its transfer.

Unstructured Storage Friendly

Functions

admin

Retrieve the admin address.

function admin() external view returns (address adminAddress);

Returns

pendingAdmin

Retrieve the pending admin address.

function pendingAdmin() external view returns (address pendingAdminAddress);

Returns

transferAdmin

Propose a new admin.

Only callable by the admin

function transferAdmin(address _newAdmin) external;

Parameters

acceptAdmin

Accept an admin transfer.

Only callable by the pending admin

function acceptAdmin() external;

Events

SetAdmin

The admin address has been changed.

event SetAdmin(address admin);

SetPendingAdmin

The pending admin address has been changed.

event SetPendingAdmin(address pendingAdmin);

ICub

Git Source

Author: mortimr @ Kiln

The cub is controlled by a Hatcher in charge of providing its status details and implementation address.

Unstructured Storage Friendly

Functions

appliedFixes

Public method that emits the AppliedFixes event.

Transparent to all callers except the cub itself

Only callable by the cub itself as a regular call

This method is used to detect the execution context (view/non-view)

function appliedFixes(address[] memory _fixers) external;

Parameters

applyFix

Applies the provided fix.

Transparent to all callers except the hatcher

function applyFix(address _fixer) external;

Parameters

Events

AppliedFixes

Emitted when several fixes have been applied.

event AppliedFixes(address[] fixes);

Errors

FixDelegateCallError

An error occured when performing the delegatecall to the fix.

error FixDelegateCallError(address fixer, bytes err);

FixCallError

The fix method failed by returning false.

error FixCallError(address fixer);

CalledWhenPaused

A call was made while the cub was paused.

error CalledWhenPaused(address caller);

CubAlreadyInitialized

error CubAlreadyInitialized();

IDepositor

Git Source

Author: mortimr @ Kiln

The Depositor contract adds deposit capabilities to easily fund validators and activate them on the Consensus Layer.

Unstructured Storage Friendly

Functions

depositContract

Retrieve the deposit contract address.

function depositContract() external view returns (address depositContractAddress);

Returns

Events

SetDepositContract

The deposit contract address has been updated.

event SetDepositContract(address depositContract);

Errors

InvalidPublicKeyLength

The provided public key is not 48 bytes long.

error InvalidPublicKeyLength();

InvalidSignatureLength

The provided signature is not 96 bytes long.

error InvalidSignatureLength();

InvalidDepositSize

The balance is too low for the deposit.

error InvalidDepositSize();

DepositError

An error occured during the deposit.

error DepositError();

IFixable

Git Source

Author: mortimr @ Kiln

The Fixable contract can be used on cubs to expose a safe noop to force a fix.

Unstructured Storage Friendly

Functions

fix

Noop method to force a global fix to be applied.

function fix() external;

IFixer

Git Source

Author: mortimr @ Kiln

The Hatcher can deploy, upgrade, fix and pause a set of instances called cubs. All cubs point to the same common implementation.

Unstructured Storage Friendly

Functions

fix

Interface to implement on a Fixer contract.

function fix() external returns (bool isFixed);

Returns

IHatcher

Git Source

Inherits: IBeacon

Author: mortimr @ Kiln

The Hatcher can deploy, upgrade, fix and pause a set of instances called cubs. All cubs point to the same coomon implementation.

Unstructured Storage Friendly

Functions

implementation

Retrieve the common implementation.

function implementation() external view returns (address implementationAddress);

Returns

status

Retrieve cub status details.

function status(address cub) external view returns (address implementationAddress, bool hasFixes, bool isPaused);

Parameters

Returns

initialProgress

Retrieve the initial progress.

This value is the starting progress value for all new cubs

function initialProgress() external view returns (uint256 currentInitialProgress);

Returns

progress

Retrieve the current progress of a specific cub.

function progress(address cub) external view returns (uint256 currentProgress);

Parameters

Returns

globalPaused

Retrieve the global pause status.

function globalPaused() external view returns (bool isGlobalPaused);

Returns

paused

Retrieve a cub pause status.

function paused(address cub) external view returns (bool isPaused);

Parameters

Returns

pauser

Retrieve the address of the pauser.

function pauser() external view returns (address);

fixes

Retrieve a cub's global fixes that need to be applied, taking its progress into account.

function fixes(address cub) external view returns (address[] memory fixesAddresses);

Parameters

Returns

globalFixes

Retrieve the raw list of global fixes.

function globalFixes() external view returns (address[] memory globalFixesAddresses);

Returns

nextHatch

Retrieve the address of the next hatched cub.

function nextHatch() external view returns (address nextHatchedCub);

Returns

frozen

Retrieve the freeze status.

function frozen() external view returns (bool);

Returns

freezeTime

Retrieve the timestamp when the freeze happens.

function freezeTime() external view returns (uint256);

Returns

hatch

Creates a new cub.

function hatch(bytes calldata cdata) external returns (address cubAddress);

Parameters

Returns

hatch

Creates a new cub, without calldata.

function hatch() external returns (address cubAddress);

Returns

commitFixes

Sets the progress of the caller to the current global fixes array length.

function commitFixes() external;

setPauser

Sets the address of the pauser.

function setPauser(address newPauser) external;

Parameters

applyFixToCubs

Apply a fix to several cubs.

function applyFixToCubs(address fixer, address[] calldata cubs) external;

Parameters

applyFixesToCub

Apply several fixes to one cub.

function applyFixesToCub(address cub, address[] calldata fixers) external;

Parameters

registerGlobalFix

Register a new global fix for cubs to call asynchronously.

function registerGlobalFix(address fixer) external;

Parameters

deleteGlobalFix

Deletes a global fix from the array.

function deleteGlobalFix(uint256 index) external;

Parameters

upgradeTo

Upgrades the common implementation address.

function upgradeTo(address newImplementation) external;

Parameters

upgradeToAndChangeInitialProgress

Upgrades the common implementation address and the initial progress value.

function upgradeToAndChangeInitialProgress(address newImplementation, uint256 initialProgress_) external;

Parameters

setInitialProgress

Sets the initial progress value.

function setInitialProgress(uint256 initialProgress_) external;

Parameters

setCubProgress

Sets the progress of a cub.

function setCubProgress(address cub, uint256 newProgress) external;

Parameters

pauseCubs

Pauses a set of cubs.

function pauseCubs(address[] calldata cubs) external;

Parameters

unpauseCubs

Unpauses a set of cubs.

function unpauseCubs(address[] calldata cubs) external;

Parameters

globalPause

Pauses all the cubs of the system.

function globalPause() external;

globalUnpause

Unpauses all the cubs of the system.

If a cub was specifically paused, this method won't unpause it

function globalUnpause() external;

freeze

Sets the freeze timestamp.

function freeze(uint256 freezeTimeout) external;

Parameters

cancelFreeze

Cancels the freezing procedure.

function cancelFreeze() external;

Events

GlobalPause

Emitted when the system is globally paused.

event GlobalPause();

GlobalUnpause

Emitted when the system is globally unpaused.

event GlobalUnpause();

Pause

Emitted when a specific cub is paused.

event Pause(address cub);

Unpause

Emitted when a specific cub is unpaused.

event Unpause(address cub);

DeletedGlobalFix

Emitted when a global fix is removed.

event DeletedGlobalFix(uint256 index);

AppliedFix

Emitted when a cub has properly applied a fix.

event AppliedFix(address cub, address fix);

Upgraded

Emitted the common implementation is updated.

event Upgraded(address indexed implementation);

Hatched

Emitted a new cub is hatched.

event Hatched(address indexed cub, bytes cdata);

SetInitialProgress

Emitted a the initial progress has been changed.

event SetInitialProgress(uint256 initialProgress);

SetPauser

Emitted a new pauser is set.

event SetPauser(address pauser);

CommittedFixes

Emitted a cub committed some global fixes.

event CommittedFixes(address cub, uint256 progress);

RegisteredGlobalFix

Emitted a global fix is registered.

event RegisteredGlobalFix(address fix, uint256 index);

Errors

ImplementationNotAContract

The provided implementation is not a smart contract.

error ImplementationNotAContract(address implementation);

INFT

Git Source

Inherits: IERC721Metadata

Author: mortimr @ Kiln

NFT contract using utils.sol storage format.

Functions

totalSupply

Retrieve the total count of validator created with this contract.

function totalSupply() external view returns (uint256);

Returns

Events

SetName

Emitted when name is changed.

event SetName(string name);

SetSymbol

Emitted when symbol is changed.

event SetSymbol(string symbol);

Errors

TokenAlreadyMinted

Thrown when the token is already minted when it shouldn't.

error TokenAlreadyMinted(uint256 tokenId);

IllegalMintToZero

Thrown when a mint operation to address zero is attempted.

error IllegalMintToZero();

IllegalTransferToZero

Thrown when a transfer operation to address zero is attempted.

error IllegalTransferToZero();

ApprovalToOwner

Thrown when approval to self is made.

error ApprovalToOwner(address owner);

InvalidTokenId

Thrown when provided token id is invalid.

error InvalidTokenId(uint256 tokenId);

NonERC721ReceiverTransfer

Thrown when the receiving contract is not able to receive the token.

error NonERC721ReceiverTransfer(address from, address to, uint256 tokenId, bytes data);

IllegalTransferWhileFrozen

Throw when an nft transfer was attempted while the nft is frozen. NFTs get frozen for ever once the exit request is made. NFTs get frozen for 6 hours when a withdrawal is made.

error IllegalTransferWhileFrozen(uint256 tokenId, uint256 currentTimestamp, uint256 freezeTimestamp);

IProxyFactory

Git Source

Inherits: IAdministrable

Author: mortimr @ Kiln

Proxy Factory deploys proxy that are setup to work and give the ownership to a configurable owner.

Unstructured Storage Friendly

Functions

deploy

Deploys a new proxy ready to be used.

function deploy(bytes32 channel, address owner, address implementation, bytes calldata cdata)
    external
    returns (address);

Parameters

Events

DeployedProxy

Emitted when a new proxy is deployed.

event DeployedProxy(bytes32 channel, address proxy, address implementation, bytes cdata, address admin);

Contents

• LibAddress
• LibBytes
• LibConstant
• LibErrors
• LibKey
• LibPublicKey
• LibSanitize
• LibSignature
• LibUint256

LibAddress

Git Source

This library helps manipulating addresses.

State Variables

ETH1_PREFIX

The base mask used to generate a bytes32 withdrawal credential from an address.

uint256 constant ETH1_PREFIX = 0x0100000000000000000000000000000000000000000000000000000000000000;

Functions

toWithdrawalCredentials

Utility to convert an address into withdrawal credentials.

function toWithdrawalCredentials(address addr) internal pure returns (bytes32);

Parameters

Returns

fromWithdrawalCredentials

Utility to convert withdrawal credentials back to an address.

function fromWithdrawalCredentials(bytes32 withdrawalCredentials) internal pure returns (address);

Parameters

Returns

LibBytes

Git Source

This library helps manipulating bytes.

Functions

slice

Slices the provided bytes.

function slice(bytes memory bytes_, uint256 start, uint256 length) internal pure returns (bytes memory);

Parameters

Returns

Errors

SliceOverflow

The length overflows an uint.

error SliceOverflow();

SliceOutOfBounds

The slice is outside of the initial bytes bounds.

error SliceOutOfBounds();

LibConstant

Git Source

State Variables

BASIS_POINTS_MAX

The basis points value representing 100%.

uint256 internal constant BASIS_POINTS_MAX = 10_000;

DEPOSIT_SIZE

The size of a deposit to activate a validator.

uint256 internal constant DEPOSIT_SIZE = 32 ether;

MINIMUM_FREEZE_TIMEOUT

The minimum freeze timeout before freeze is active.

uint256 internal constant MINIMUM_FREEZE_TIMEOUT = 100 days;

ETHER

Address used to represent ETH when an address is required to identify an asset.

address internal constant ETHER = 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE;

LibErrors

Git Source

Errors

Unauthorized

error Unauthorized(address account, address expected);

InvalidZeroAddress

error InvalidZeroAddress();

InvalidNullValue

error InvalidNullValue();

InvalidBPSValue

error InvalidBPSValue();

InvalidEmptyString

error InvalidEmptyString();

LibKey

Git Source

State Variables

KEY_PAIR_LENGTH

uint256 constant KEY_PAIR_LENGTH = LibPublicKey.PUBLIC_KEY_LENGTH + LibSignature.SIGNATURE_LENGTH;

Functions

toBytes

function toBytes(LibPublicKey.PublicKey memory publicKey, LibSignature.Signature memory signature)
    internal
    pure
    returns (bytes memory);

fromBytes

function fromBytes(bytes memory keys)
    internal
    pure
    returns (LibPublicKey.PublicKey memory publicKey, LibSignature.Signature memory signature);

LibPublicKey

Git Source

State Variables

PUBLIC_KEY_LENGTH

uint256 constant PUBLIC_KEY_LENGTH = 48;

PADDING

bytes constant PADDING = hex"00000000000000000000000000000000";

Functions

toBytes

function toBytes(PublicKey memory publicKey) internal pure returns (bytes memory);

fromBytes

function fromBytes(bytes memory publicKey) internal pure returns (PublicKey memory ret);

Structs

PublicKey

struct PublicKey {
    bytes32 A;
    bytes16 B;
}

LibSanitize

Git Source

This library helps sanitizing inputs.

Functions

notZeroAddress

Internal utility to sanitize an address and ensure its value is not 0.

function notZeroAddress(address addressValue) internal pure;

Parameters

notNullValue

Internal utility to sanitize an uint256 value and ensure its value is not 0.

function notNullValue(uint256 value) internal pure;

Parameters

notInvalidBps

Internal utility to sanitize a bps value and ensure it's <= 100%.

function notInvalidBps(uint256 value) internal pure;

Parameters

notEmptyString

Internal utility to sanitize a string value and ensure it's not empty.

function notEmptyString(string memory stringValue) internal pure;

Parameters

LibSignature

Git Source

State Variables

SIGNATURE_LENGTH

uint256 constant SIGNATURE_LENGTH = 96;

Functions

toBytes

function toBytes(Signature memory signature) internal pure returns (bytes memory);

fromBytes

function fromBytes(bytes memory signature) internal pure returns (Signature memory ret);

Structs

Signature

struct Signature {
    bytes32 A;
    bytes32 B;
    bytes32 C;
}

LibUint256

Git Source

Functions

min

function min(uint256 x, uint256 y) internal pure returns (uint256 z);

max

function max(uint256 x, uint256 y) internal pure returns (uint256 z);

mulDiv

function mulDiv(uint256 a, uint256 b, uint256 c) internal pure returns (uint256);

ceil

function ceil(uint256 num, uint256 den) internal pure returns (uint256);

Contents

• LAddress
• CAddress
• LArray
• LBool
• CBool
• LBytes32
• CBytes32
• LMapping
• LString
• types
• LUint256
• CUint256

LAddress

Git Source

Library Address - Address slot utilities.

Functions

get

function get(types.Address position) internal view returns (address data);

set

function set(types.Address position, address data) internal;

del

function del(types.Address position) internal;

CAddress

Git Source

Functions

toUint256

function toUint256(address val) internal pure returns (uint256);

toBytes32

function toBytes32(address val) internal pure returns (bytes32);

toBool

function toBool(address val) internal pure returns (bool converted);

k

This method should be used to convert an address to a uint256 when used as a key in a mapping.

function k(address val) internal pure returns (uint256);

v

This method should be used to convert an address to a uint256 when used as a value in a mapping.

function v(address val) internal pure returns (uint256);

LArray

Git Source

Functions

toUintA

function toUintA(types.Array position) internal pure returns (uint256[] storage data);

toAddressA

function toAddressA(types.Array position) internal pure returns (address[] storage data);

toBoolA

function toBoolA(types.Array position) internal pure returns (bool[] storage data);

toBytes32A

function toBytes32A(types.Array position) internal pure returns (bytes32[] storage data);

del

function del(types.Array position) internal;

dangerousDirtyDel

This delete can be used if and only if we only want to clear the length of the array. Doing so will create an array that behaves like an empty array in solidity. It can have advantages if we often rewrite to the same slots of the array. Prefer using del if you don't know what you're doing.

function dangerousDirtyDel(types.Array position) internal;

LBool

Git Source

Functions

get

function get(types.Bool position) internal view returns (bool data);

set

function set(types.Bool position, bool data) internal;

del

function del(types.Bool position) internal;

CBool

Git Source

Functions

toBytes32

function toBytes32(bool val) internal pure returns (bytes32);

toAddress

function toAddress(bool val) internal pure returns (address);

toUint256

function toUint256(bool val) internal pure returns (uint256 converted);

k

This method should be used to convert a bool to a uint256 when used as a key in a mapping.

function k(bool val) internal pure returns (uint256);

v

This method should be used to convert a bool to a uint256 when used as a value in a mapping.

function v(bool val) internal pure returns (uint256);

LBytes32

Git Source

Functions

get

function get(types.Bytes32 position) internal view returns (bytes32 data);

set

function set(types.Bytes32 position, bytes32 data) internal;

del

function del(types.Bytes32 position) internal;

CBytes32

Git Source

Functions

toUint256

function toUint256(bytes32 val) internal pure returns (uint256);

toAddress

function toAddress(bytes32 val) internal pure returns (address);

toBool

function toBool(bytes32 val) internal pure returns (bool converted);

k

This method should be used to convert a bytes32 to a uint256 when used as a key in a mapping.

function k(bytes32 val) internal pure returns (uint256);

v

This method should be used to convert a bytes32 to a uint256 when used as a value in a mapping.

function v(bytes32 val) internal pure returns (uint256);

LMapping

Git Source

Functions

get

function get(types.Mapping position) internal pure returns (mapping(uint256 => uint256) storage data);

LString

Git Source

Functions

get

function get(types.String position) internal view returns (string memory);

set

function set(types.String position, string memory value) internal;

Structs

StringStorage

struct StringStorage {
    string value;
}

types

Git Source

Library holding bytes32 custom types

LUint256

Git Source

Functions

get

function get(types.Uint256 position) internal view returns (uint256 data);

set

function set(types.Uint256 position, uint256 data) internal;

del

function del(types.Uint256 position) internal;

CUint256

Git Source

Functions

toBytes32

function toBytes32(uint256 val) internal pure returns (bytes32);

toAddress

function toAddress(uint256 val) internal pure returns (address);

toBool

function toBool(uint256 val) internal pure returns (bool);

Contents

• LOperatorApprovalsMapping
• uctypes

LOperatorApprovalsMapping

Git Source

Functions

get

function get(uctypes.OperatorApprovalsMapping position)
    internal
    pure
    returns (mapping(address => mapping(address => bool)) storage data);

uctypes

Git Source

Administrable

Git Source

Inherits: IAdministrable

Author: mortimr @ Kiln

This contract provides all the utilities to handle the administration and its transfer.

Unstructured Storage Friendly

State Variables

$admin

The admin address in storage.

Slot: keccak256(bytes("administrable.admin")) - 1

types.Address internal constant $admin =
    types.Address.wrap(0x927a17e5ea75d9461748062a2652f4d3698a628896c9832f8488fa0d2846af09);

$pendingAdmin

The pending admin address in storage.

Slot: keccak256(bytes("administrable.pendingAdmin")) - 1

types.Address internal constant $pendingAdmin =
    types.Address.wrap(0x3c1eebcc225c6cc7f5f8765767af6eff617b4139dc3624923a2db67dbca7b68e);

Functions

onlyAdmin

This modifier ensures that only the admin is able to call the method.

modifier onlyAdmin();

onlyPendingAdmin

This modifier ensures that only the pending admin is able to call the method.

modifier onlyPendingAdmin();

admin

Retrieve the admin address.

function admin() external view returns (address);

Returns

pendingAdmin

Retrieve the pending admin address.

function pendingAdmin() external view returns (address);

Returns

transferAdmin

Propose a new admin.

Only callable by the admin.

function transferAdmin(address newAdmin) external onlyAdmin;

Parameters

acceptAdmin

Accept an admin transfer.

Only callable by the pending admin.

function acceptAdmin() external onlyPendingAdmin;

_getAdmin

Retrieve the admin address.

function _getAdmin() internal view returns (address);

Returns

_setAdmin

Change the admin address.

function _setAdmin(address newAdmin) internal;

Parameters

_getPendingAdmin

Retrieve the pending admin address.

function _getPendingAdmin() internal view returns (address);

Returns

_setPendingAdmin

Change the pending admin address.

function _setPendingAdmin(address newPendingAdmin) internal;

Parameters

Cub

Git Source

Inherits: Proxy, ERC1967Upgrade, ICub

Author: mortimr @ Kiln

The cub is controlled by a Hatcher in charge of providing its status details and implementation address.

Unstructured Storage Friendly

Functions

___initializeCub

Initializer to not rely on the constructor.

function ___initializeCub(address beacon, bytes memory data) external;

Parameters

_implementation

Internal utility to retrieve the implementation from the beacon.

function _implementation() internal view virtual override returns (address);

Returns

onlyBeacon

Prevents unauthorized calls.

This will make the method transparent, forcing unauthorized callers into the fallback.

modifier onlyBeacon();

onlyMe

Prevents unauthorized calls.

This will make the method transparent, forcing unauthorized callers into the fallback.

modifier onlyMe();

appliedFixes

Public method that emits the AppliedFixes event.

Transparent to all callers except the cub itself

function appliedFixes(address[] memory fixers) public onlyMe;

Parameters

applyFix

Applies the provided fix.

Transparent to all callers except the hatcher

function applyFix(address fixer) external onlyBeacon;

Parameters

_fixes

Retrieve the list of fixes for this cub from the hatcher.

function _fixes(address beacon) internal view returns (address[] memory);

Parameters

Returns

_status

Retrieve the status for this cub from the hatcher.

function _status(address beacon) internal view returns (address, bool, bool);

Parameters

Returns

_commit

Commits fixes to the hatcher.

function _commit(address beacon) internal;

Parameters

_fix

Fetches the current cub status and acts accordingly.

function _fix(address beacon) internal returns (address);

Parameters

_applyFix

Applies the given fix, and reverts in case of error.

function _applyFix(address fixer) internal;

Parameters

_fallback

Fallback method that ends up forwarding calls as delegatecalls to the implementation.

function _fallback() internal override(Proxy);

Depositor

Git Source

Inherits: IDepositor

Author: mortimr @ Kiln

The Depositor contract adds deposit capabilities to easily fund validators and activate them on the Consensus Layer.

Unstructured Storage Friendly

State Variables

$depositContract

The address of the Deposit Contract in storage.

Slot: keccak256(bytes("depositor.depositContract"))) - 1

types.Address internal constant $depositContract =
    types.Address.wrap(0x51b708339b28db69fafc07d2fc5a46c3487f5c5cd1fcb575eb01044dd8dd4de5);

DEPOSIT_SIZE_AMOUNT_LITTLEENDIAN64

Precomputed deposit size amount in little endian.

uint256 internal constant DEPOSIT_SIZE_AMOUNT_LITTLEENDIAN64 =
    0x0040597307000000000000000000000000000000000000000000000000000000;

Functions

depositContract

Retrieve the deposit contract address.

function depositContract() external view returns (address);

Returns

_setDepositContract

Set the deposit contract address in storage.

function _setDepositContract(address _depositContract) internal;

Parameters

_deposit

Utility to perform a deposit of the provided keys and the current balance.

The current balance is used for the deposit.

function _deposit(bytes memory _publicKey, bytes memory _signature, address _withdrawal) internal;

Parameters

Fixable

Git Source

Inherits: IFixable

Author: mortimr @ Kiln

The Fixable contract can be used on cubs to expose a safe noop to force a fix.

Unstructured Storage Friendly

Functions

fix

Noop method to force a global fix to be applied.

function fix() external;

Freezable

Git Source

Author: mortimr @ Kiln

The Freezable contract is used to add a freezing capability to admin related actions. The goal would be to ossify an implementation after a certain amount of time.

Unstructured Storage Friendly

State Variables

_FREEZE_TIMESTAMP_SLOT

This is the keccak-256 hash of "freezable.freeze_timestamp" subtracted by 1.

bytes32 private constant _FREEZE_TIMESTAMP_SLOT = 0x04b06dd5becaad633b58f99e01f1e05103eff5a573d10d18c9baf1bc4e6bfd3a;

Functions

onlyFreezer

Only callable by the freezer account.

modifier onlyFreezer();

notFrozen

Only callable when not frozen.

modifier notFrozen();

_getFreezer

Override and set it to return the address to consider as the freezer.

function _getFreezer() internal view virtual returns (address);

Returns

_isFrozen

Retrieve the freeze status.

function _isFrozen() internal view returns (bool);

Returns

_freezeTime

Retrieve the freeze timestamp.

function _freezeTime() internal view returns (uint256);

Returns

_setFreezeTime

Internal utility to set the freeze timestamp.

function _setFreezeTime(uint256 freezeTime) internal;

Parameters

_onlyFreezer

Internal utility to revert if caller is not freezer.

function _onlyFreezer() internal view;

_notFrozen

Internal utility to revert if contract is frozen.

function _notFrozen() internal view;

_freeze

Internal utility to start the freezing procedure.

function _freeze(uint256 freezeTimeout) internal;

Parameters

_cancelFreeze

Internal utility to cancel the freezing procedure.

function _cancelFreeze() internal;

Events

SetFreezeTime

Emitted when the freeze timeout is changed.

event SetFreezeTime(uint256 freezeTime);

Errors

Frozen

Thrown when a call happened while it was forbidden when frozen.

error Frozen();

FreezeTimeoutTooLow

Thrown when the provided timeout value is lower than 100 days.

error FreezeTimeoutTooLow(uint256 providedValue, uint256 minimumValue);

Hatcher

Git Source

Inherits: Administrable, Freezable, IHatcher

Author: mortimr @ Kiln

This contract provides all the utilities to handle the administration and its transfer

Unstructured Storage Friendly.

In general, regarding the fixes, try to always perform atomic actions to apply them.

When using regular fixes, it's already the case.

When using global fixes, try to wrap multiple actions in one tx/bundle to create the global fix and apply it on required instances.

When removing a global fix, keep in mind that the action can be front runned and the fix that should be removed would be applied.

The hatcher can be frozen by the admin. Once frozen, no more upgrade, pausing or fixing is allowed.

If frozen and paused, a cub will be unpaused.

If frozen and pending fixes are still there, they will be applied to cubs that haven't applied them.

If frozen, pending fixes cannot be removed.

Initial progress and cub progress can get updated by the admin. This means a fix can be applied twice if progress is decreased.

State Variables

$pauser

Unstructured Storage Helper for hatcher.pauser.

Holds the pauser address.

Slot: keccak256(bytes("hatcher.pauser")) - 1

types.Address internal constant $pauser =
    types.Address.wrap(0x67ad2ba345683ea58e6dcc49f12611548bc3a5b2c8c753edc1878aa0a76c3ce2);

$implementation

Unstructured Storage Helper for hatcher.implementation.

Holds the common implementation used by all the cubs.

Slot: keccak256(bytes("hatcher.implementation")) - 1

types.Address internal constant $implementation =
    types.Address.wrap(0x5822215992e9fc50486d8256024d96ad28d5ca5cb787840aef51159121dccd9d);

$initialProgress

Unstructured Storage Helper for hatcher.initialProgress.

Holds the initial progress value given to all new cubs.

Supersedes the progress of old cubs if the value is higher than their progress.

Slot: keccak256(bytes("hatcher.initialProgress")) - 1

types.Uint256 internal constant $initialProgress =
    types.Uint256.wrap(0x4a267ea82c1f4624b3dc08ad19614228bbdeee20d07eb9966d67c16d39550d77);

$fixProgresses

Unstructured Storage Helper for hatcher.fixProgresses.

Holds the value of the fix progress of every cub.

Type: mapping (address => uint256)

Slot: keccak256(bytes("hatcher.fixProgresses")) - 1

types.Mapping internal constant $fixProgresses =
    types.Mapping.wrap(0xa7208bf4db7440ac9388b234d45a5b207976f0fc12d31bf9eaa80e4e2fc0d57c);

$pauseStatus

Unstructured Storage Helper for hatcher.pauseStatus.

Holds the pause status of every cub.

Type: mapping (address => bool)

Slot: keccak256(bytes("hatcher.pauseStatus")) - 1

types.Mapping internal constant $pauseStatus =
    types.Mapping.wrap(0xd0ad769ee84b03ff353d2cb4c134ab25db1f330b56357f28eadc5b28c2f88991);

$globalPauseStatus

Unstructured Storage Helper for hatcher.globalPauseStatus.

Holds the global pause status.

Slot: keccak256(bytes("hatcher.globalPauseStatus")) - 1

types.Bool internal constant $globalPauseStatus =
    types.Bool.wrap(0x798f8d9ad9ed68e65653cd13b4f27162f01222155b56622ae81337e4888e20c0);

$fixes

Unstructured Storage Helper for hatcher.fixes.

Holds the array of global fixes.

Slot: keccak256(bytes("hatcher.fixes")) - 1

types.Array internal constant $fixes =
    types.Array.wrap(0xa8612761e880b1989e2ad0bb2c51004fad089f897b1cd8dc3dbfeae33493df55);

$creationSalt

Unstructured Storage Helper for hatcher.initialProgress.

Holds the create2 salt.

Slot: keccak256(bytes("hatcher.creationSalt")) - 1

types.Uint256 internal constant $creationSalt =
    types.Uint256.wrap(0x7b4670a3a88a40c4de314967df154b504cc215cbd280a064c677342c49c2759d);

Functions

onlyAdminOrPauser

Only allows admin or pauser to perform the call.

modifier onlyAdminOrPauser();

implementation

Retrieve the common implementation.

function implementation() external view returns (address);

Returns

status

Retrieve cub status details.

function status(address cub) external view returns (address, bool, bool);

Parameters

Returns

initialProgress

Retrieve the initial progress.

This value is the starting progress value for all new cubs

function initialProgress() external view returns (uint256);

Returns

progress

Retrieve the current progress of a specific cub.

function progress(address cub) external view returns (uint256);

Parameters

Returns

globalPaused

Retrieve the global pause status.

function globalPaused() external view returns (bool);

Returns

paused

Retrieve a cub pause status.

function paused(address cub) external view returns (bool);

Parameters

Returns

pauser

Retrieve the address of the pauser.

function pauser() external view returns (address);

fixes

Retrieve a cub's global fixes that need to be applied, taking its progress into account.

function fixes(address cub) external view returns (address[] memory);

Parameters

Returns

globalFixes

Retrieve the raw list of global fixes.

This method is not view because it reads the fixes from storage.

function globalFixes() external pure returns (address[] memory);

Returns

nextHatch

Retrieve the address of the next hatched cub.

function nextHatch() external view returns (address);

Returns

frozen

Retrieve the freeze status.

function frozen() external view returns (bool);

Returns

freezeTime

Retrieve the timestamp when the freeze happens.

function freezeTime() external view returns (uint256);

Returns

hatch

Creates a new cub.

function hatch(bytes calldata cdata) external virtual onlyAdmin returns (address);

Parameters

Returns

hatch

Creates a new cub.

function hatch() external virtual onlyAdmin returns (address);

Returns

commitFixes

Sets the progress of the caller to the current global fixes array length.

function commitFixes() external;

setPauser

Sets the address of the pauser.

function setPauser(address newPauser) external onlyAdmin;

Parameters

applyFixToCubs

Apply a fix to several cubs.

function applyFixToCubs(address fixer, address[] calldata cubs) external notFrozen onlyAdmin;

Parameters

applyFixesToCub

Apply several fixes to one cub.

function applyFixesToCub(address cub, address[] calldata fixers) external notFrozen onlyAdmin;

Parameters

registerGlobalFix

Register a new global fix for cubs to call asynchronously.

function registerGlobalFix(address fixer) external notFrozen onlyAdmin;

Parameters

deleteGlobalFix

Deletes a global fix from the array.

function deleteGlobalFix(uint256 index) external notFrozen onlyAdmin;

Parameters

upgradeTo

Upgrades the common implementation address.

function upgradeTo(address newImplementation) external notFrozen onlyAdmin;

Parameters

upgradeToAndChangeInitialProgress

Upgrades the common implementation address and the initial progress value.

function upgradeToAndChangeInitialProgress(address newImplementation, uint256 initialProgress_)
    external
    notFrozen
    onlyAdmin;

Parameters

setInitialProgress

Sets the initial progress value.

function setInitialProgress(uint256 initialProgress_) external notFrozen onlyAdmin;

Parameters

setCubProgress

Sets the progress of a cub.

function setCubProgress(address cub, uint256 newProgress) external notFrozen onlyAdmin;

Parameters

pauseCubs

Pauses a set of cubs.

function pauseCubs(address[] calldata cubs) external notFrozen onlyAdminOrPauser;

Parameters

unpauseCubs

Unpauses a set of cubs.

function unpauseCubs(address[] calldata cubs) external notFrozen onlyAdmin;

Parameters

globalPause

Pauses all the cubs of the system.

function globalPause() external notFrozen onlyAdminOrPauser;

globalUnpause

Unpauses all the cubs of the system.

If a cub was specifically paused, this method won't unpause it

function globalUnpause() external notFrozen onlyAdmin;

freeze

Sets the freeze timestamp.

function freeze(uint256 freezeTimeout) external;

Parameters

cancelFreeze

Cancels the freezing procedure.

function cancelFreeze() external;

_setPauser

Internal utility to set the pauser address.

function _setPauser(address newPauser) internal;

Parameters

_setImplementation

Internal utility to change the common implementation.

Reverts if the new implementation is not a contract.

function _setImplementation(address newImplementation) internal;

Parameters

_nextHatch

Internal utility to retrieve the address of the next deployed Cub.

function _nextHatch() internal view returns (address);

Returns

_hatch

Internal utility to create a new Cub.

The provided cdata is used to perform an atomic call upon contract creation.

function _hatch(bytes memory cdata) internal returns (address cub);

Parameters

_pause

Internal utility to pause a cub.

function _pause(address cub) internal;

Parameters

_unpause

Internal utility to unpause a cub.

function _unpause(address cub) internal;

Parameters

_setInitialProgress

Internal utility to set the initial cub progress.

This value defines where the new cubs should start applying fixes from the global fix array.

This value supersedes existing cub progresses if the progress is lower than this value.

function _setInitialProgress(uint256 initialProgress_) internal;

Parameters

_getFreezer

Internal utility to retrieve the address of the freezer.

function _getFreezer() internal view override returns (address);

Returns

Implementation

Git Source

Author: mortimr @ Kiln

This contracts must be used on all implementation contracts. It ensures that the initializers are only callable through the proxy. This will brick the implementation and make it unusable directly without using delegatecalls.

Unstructured Storage Friendly

State Variables

$initializableVersion

The version number in storage in the initializable contract.

Slot: keccak256(bytes("initializable.version"))) - 1

types.Uint256 internal constant $initializableVersion =
    types.Uint256.wrap(0xc4c7f1ccb588f39a9aa57be6cfd798d73912e27b44cfa18e1a5eba7b34e81a76);

Functions

constructor

constructor();

Initializable

Git Source

Author: mortimr @ Kiln

This contracts helps upgradeable contracts handle an internal version value to prevent initializer replays.

Unstructured Storage Friendly

State Variables

$version

The version number in storage.

Slot: keccak256(bytes("initializable.version"))) - 1

types.Uint256 internal constant $version =
    types.Uint256.wrap(0xc4c7f1ccb588f39a9aa57be6cfd798d73912e27b44cfa18e1a5eba7b34e81a76);

Functions

init

The modifier to use on initializers.

Do not provide _version dynamically, make sure the value is hard-coded each time the modifier is used.

modifier init(uint256 _version);

Parameters

Events

Initialized

The version has been initialized.

event Initialized(uint256 version, bytes cdata);

Errors

AlreadyInitialized

The init modifier has already been called on the given version number.

error AlreadyInitialized(uint256 version, uint256 currentVersion);

NFT

Git Source

Inherits: INFT

Author: mortimr @ Kiln

NFT contract using utils.sol storage format.

State Variables

$name

ERC721 name of the contract.

Slot: keccak256(bytes("nft.1.name")) - 1

types.String internal constant $name =
    types.String.wrap(0x8be0d77374e3002afd46fd09ae2c8e3afc7315322504f7f1a09d189f4925e72f);

$symbol

ERC721 symbol of the contract.

Slot: keccak256(bytes("nft.1.symbol")) - 1

types.String internal constant $symbol =
    types.String.wrap(0xddad2df2277e0186b34991db0b7ceafa36b49b76d0a1e87f6e4d44b6b17a207f);

$mintCounter

Internal ID counter to keep track of minted tokens.

Slot: keccak256(bytes("nft.1.mintCounter")) - 1

types.Uint256 internal constant $mintCounter =
    types.Uint256.wrap(0x3d706fc25ad0e96a2c3fb1b58cdd70ba377f331d59f761caecaf2f3a236d99a1);

$burnCounter

Internal burn counter used to keep track of the total supply.

Slot: keccak256(bytes("nft.1.burnCounter")) - 1

types.Uint256 internal constant $burnCounter =
    types.Uint256.wrap(0x0644144c18bf2aa8e15d5433cc3f6e2273ab9ccd122cd4f430275a2997cc0dc2);

$owners

Internal mapping that holds the links between owners and NFT IDs.

Type: mapping (uint256 => address)

Slot: keccak256(bytes("nft.1.owners")) - 1

types.Mapping internal constant $owners =
    types.Mapping.wrap(0xc1f66d46ebf7070ef20209d66f741219b00fb896714319503d158a28b0d103d3);

$balances

Internal mapping that holds the balances of every owner (how many NFTs they own).

Type: mapping (address => uint256)

Slot: keccak256(bytes("nft.1.balances")) - 1

types.Mapping internal constant $balances =
    types.Mapping.wrap(0xf9245bc1df90ea86e77b9f2423fe9cc12aa083c8ab9a55e727b285192b30d98a);

$tokenApprovals

Internal mapping that holds the token approval data.

Type: mapping (uint256 => address)

Slot: keccak256(bytes("nft.1.tokenApprovals")) - 1

types.Mapping internal constant $tokenApprovals =
    types.Mapping.wrap(0x3790264503275ecd52e8f0b419eb5ce016ca8a1f0fbac5a9ede429d0c1732004);

$operatorApprovals

Internal mapping of operator approvals.

Type: mapping (address => mapping (address => bool))

Slot: keccak256(bytes("nft.1.operatorApprovals")) - 1

uctypes.OperatorApprovalsMapping internal constant $operatorApprovals =
    uctypes.OperatorApprovalsMapping.wrap(0x6c716a91f6b5f5a0aa2affaf44bd88ea94ec69e363cf1fe9251e00a0fcc6c34e);

Functions

initializeNFT

Internal initializer to call when first deploying the contract.

function initializeNFT(string memory name_, string memory symbol_) internal;

tokenURI

Returns the token uri for the given token id.

To override

function tokenURI(uint256 tokenId) external view virtual returns (string memory);

Parameters

_onTransfer

Internal hook happening at each transfer. Not called during mint or burn. Use _onMint and _onBurn instead. The hook is called before state transitions are made.

To override

function _onTransfer(address from, address to, uint256 tokenId) internal virtual;

Parameters

_onMint

Internal hook happening at each mint. The hook is called before state transitions are made.

To override

function _onMint(address to, uint256 tokenId) internal virtual;

Parameters

_onBurn

Internal hook happening at each burn. The hook is called before state transitions are made.

To override

function _onBurn(uint256 tokenId) internal virtual;

Parameters

totalSupply

Retrieve the total count of validator created with this contract.

function totalSupply() external view returns (uint256);

Returns

balanceOf

function balanceOf(address owner) public view virtual override returns (uint256);

ownerOf

function ownerOf(uint256 tokenId) public view virtual override returns (address);

name

function name() external view virtual returns (string memory);

symbol

function symbol() external view virtual returns (string memory);

supportsInterface

function supportsInterface(bytes4 interfaceId) external pure returns (bool);

approve

function approve(address to, uint256 tokenId) public virtual override;

getApproved

function getApproved(uint256 tokenId) public view virtual override returns (address);

setApprovalForAll

function setApprovalForAll(address operator, bool approved) public virtual override;

isApprovedForAll

function isApprovedForAll(address owner, address operator) public view virtual override returns (bool);

transferFrom

function transferFrom(address from, address to, uint256 tokenId) public virtual override;

safeTransferFrom

function safeTransferFrom(address from, address to, uint256 tokenId) public virtual override;

safeTransferFrom

function safeTransferFrom(address from, address to, uint256 tokenId, bytes memory data) public virtual override;

_setName

Internal utility to set the ERC721 name value.

function _setName(string memory newName) internal;

Parameters

_setSymbol

Internal utility to set the ERC721 symbol value.

function _setSymbol(string memory newSymbol) internal;

Parameters

_safeTransfer

Internal utility to perform a safe transfer (transfer + extra checks on contracts).

function _safeTransfer(address from, address to, uint256 tokenId, bytes memory data) internal virtual;

Parameters

_ownerOf

Internal utility to retrieve the owner of the specified token id.

function _ownerOf(uint256 tokenId) internal view virtual returns (address);

Parameters

Returns

_exists

Internal utility to verify if a token id exists.

function _exists(uint256 tokenId) internal view virtual returns (bool);

Parameters

Returns

_isApprovedOrOwner

Internal utility to check if the specified address is either approved by the owner or the owner for the given token id.

function _isApprovedOrOwner(address spender, uint256 tokenId) internal view virtual returns (bool);

Parameters

Returns

_safeMint

Internal utility to perform a safe mint operation (mint + extra checks on contracts).

function _safeMint(address to, uint256 tokenId, bytes memory data) internal virtual;

Parameters

_mint

Internal utility to mint the desired token id.

function _mint(address to, uint256 tokenId) internal virtual;

Parameters

_burn

Internal utility to burn the desired token id.

function _burn(uint256 tokenId) internal virtual;

Parameters

_transfer

Internal utility to perform a regular transfer of a token.

function _transfer(address from, address to, uint256 tokenId) internal virtual;

Parameters

_approve

Internal utility to approve an account for a token id.

function _approve(address to, address owner, uint256 tokenId) internal virtual;

Parameters

_setApprovalForAll

Internal utility to approve an account for all tokens of another account.

function _setApprovalForAll(address owner, address operator, bool approved) internal virtual;

Parameters

_requireExists

Internal utility to check and revert if a token doesn't exists.

function _requireExists(uint256 tokenId) internal view virtual;

Parameters

_checkOnERC721Received

Internal utility to perform checks upon transfer in the case of sending to a contract.

function _checkOnERC721Received(address from, address to, uint256 tokenId, bytes memory data) private returns (bool);

Parameters

Returns

ProxyFactory

Git Source

Inherits: IProxyFactory, Administrable

Author: mortimr @ Kiln

Proxy Factory deploys proxy that are setup to work and give the ownership to a configurable owner.

Unstructured Storage Friendly

Functions

constructor

constructor(address admin_);

Parameters

deploy

Deploys a new proxy ready to be used.

function deploy(bytes32 channel, address owner, address implementation, bytes calldata cdata)
    external
    onlyAdmin
    returns (address newProxy);

Parameters

TransparentUpgradeableProxy

Git Source

Inherits: ERC1967Proxy

Functions

constructor

Initializes an upgradeable proxy managed by _admin, backed by the implementation at _logic, and optionally initialized with _data as explained in {ERC1967Proxy-constructor}.

constructor(address _logic, address admin_, bytes memory _data) payable ERC1967Proxy(_logic, _data);

ifAdmin

Modifier used internally that will delegate the call to the implementation unless the sender is the admin.

modifier ifAdmin();

admin

Returns the current admin. NOTE: Only the admin can call this function. See {ProxyAdmin-getProxyAdmin}. TIP: To get this value clients can read directly from the storage slot shown below (specified by EIP1967) using the https://eth.wiki/json-rpc/API#eth_getstorageat[eth_getStorageAt] RPC call. 0xb53127684a568b3173ae13b9f8a6016e243e63b6e8ee1178d6a717850b5d6103

function admin() external ifAdmin returns (address admin_);

implementation

Returns the current implementation. NOTE: Only the admin can call this function. See {ProxyAdmin-getProxyImplementation}. TIP: To get this value clients can read directly from the storage slot shown below (specified by EIP1967) using the https://eth.wiki/json-rpc/API#eth_getstorageat[eth_getStorageAt] RPC call. 0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc

function implementation() external ifAdmin returns (address implementation_);

changeAdmin

Changes the admin of the proxy. Emits an {AdminChanged} event. NOTE: Only the admin can call this function. See {ProxyAdmin-changeProxyAdmin}.

function changeAdmin(address newAdmin) external virtual ifAdmin;

upgradeTo

Upgrade the implementation of the proxy. NOTE: Only the admin can call this function. See {ProxyAdmin-upgrade}.

function upgradeTo(address newImplementation) external virtual ifAdmin;

upgradeToAndCall

Upgrade the implementation of the proxy, and then call a function from the new implementation as specified by data, which should be an encoded function call. This is useful to initialize new storage variables in the proxied contract. NOTE: Only the admin can call this function. See {ProxyAdmin-upgradeAndCall}.

function upgradeToAndCall(address newImplementation, bytes calldata data) external payable virtual ifAdmin;

_beforeFallback

Makes sure the admin cannot access the fallback function. See {Proxy-_beforeFallback}.

function _beforeFallback() internal virtual override;

TUPProxy

Git Source

Inherits: TransparentUpgradeableProxy, Freezable

Author: mortimr @ Kiln

This contract extends the Transparent Upgradeable proxy and adds a system wide pause feature. When the system is paused, the fallback will fail no matter what calls are made.

State Variables

_PAUSE_SLOT

EIP1967 slot to store the pause status value.

bytes32 private constant _PAUSE_SLOT = bytes32(uint256(keccak256("eip1967.proxy.pause")) - 1);

_PAUSER_SLOT

EIP1967 slot to store the pauser address value.

bytes32 private constant _PAUSER_SLOT = bytes32(uint256(keccak256("eip1967.proxy.pauser")) - 1);

Functions

ifAdminOrPauser

modifier ifAdminOrPauser();

constructor

constructor(address _logic, address admin_, bytes memory _data)
    payable
    TransparentUpgradeableProxy(_logic, admin_, _data);

Parameters

paused

Retrieves Paused state.

function paused() external ifAdminOrPauser returns (bool);

Returns

pause

Pauses system.

function pause() external ifAdminOrPauser notFrozen;

unpause

Unpauses system.

function unpause() external ifAdmin notFrozen;

freeze

Sets the freeze timeout.

function freeze(uint256 freezeTimeout) external ifAdmin;

cancelFreeze

Cancels the freeze process.

function cancelFreeze() external ifAdmin;

frozen

Retrieve the freeze status.

function frozen() external ifAdmin returns (bool);

Returns

freezeTime

Retrieve the freeze timestamp.

function freezeTime() external ifAdmin returns (uint256);

Returns

pauser

Retrieve the dedicated pauser address.

function pauser() external ifAdminOrPauser returns (address);

Returns

changePauser

Changes the dedicated pauser address.

Not callable when frozen

function changePauser(address newPauser) external ifAdmin notFrozen;

Parameters

changeAdmin

Changed the proxy admin.

Not callable when frozen

function changeAdmin(address newAdmin) external override ifAdmin notFrozen;

upgradeTo

Performs an upgrade without reinitialization.

function upgradeTo(address newImplementation) external override ifAdmin notFrozen;

Parameters

upgradeToAndCall

Performs an upgrade with reinitialization.

function upgradeToAndCall(address newImplementation, bytes calldata data) external payable override ifAdmin notFrozen;

Parameters

_getPauser

Internal utility to retrieve the dedicated pauser from storage,

function _getPauser() internal view returns (address);

Returns

_changePauser

Internal utility to change the dedicated pauser.

function _changePauser(address newPauser) internal;

Parameters

_beforeFallback

Overrides the fallback method to check if system is not paused before.

Address Zero is allowed to perform calls even if system is paused. This allows view functions to be called when the system is paused as rpc providers can easily set the sender address to zero.

function _beforeFallback() internal override;

_getFreezer

Internal utility to retrieve the account allowed to freeze the contract.

function _getFreezer() internal view override returns (address);

Returns

Events

PauserChanged

Emitted when the proxy dedicated pauser is changed.

event PauserChanged(address previousPauser, address newPauser);

Errors

CallWhenPaused

Thrown when a call was attempted and the proxy is paused.

error CallWhenPaused();