Table of Contents


Composition of the full Habitat Rollup contracts (v1)

INSPECTION_PERIOD() returns (uint16)


Constant, the inspection period defines how long it takes (in L1 blocks) until a submitted solution can be finalized. Default: 60 blocks ~ 14 minutes.

MAX_BLOCK_SIZE() returns (uint24)


Constant, the maximum size a single block can be. Default: 31744 bytes

blockMeta(uint256 height) returns (uint256 ret)


Holds metadata for blocks. | finalization target (blockNumber) | least significant bit is a dispute flag |

canFinalizeBlock(uint256 blockNumber) returns (bool)


Returns true if blockNumber can be finalized, else false. Helper function for chain clients.

  • blockNumber The number of the block in question.

challenge() returns ()


Challenge the solution or just verify the next pending block directly. Expects the block data right after the function signature to be included in the call. calldata layout: | 4 bytes function sig | | 32 bytes size of block | | 32 bytes number of challenge rounds | | arbitrary witness data | | data of block |

deposit(address token, uint256 amountOrId, address receiver) returns ()


Deposit token and value (amountOrId) into bridge.

  • amountOrId Amount or the token id.
  • receiver The account who receives the token(s).
  • token The ERC-20/ERC-721 token address.

dispute(uint256 blockNumber, uint256 bitmask) returns ()


Flags up to 256 solutions. This will increase the inspection period for the block(s).

  • bitmask Up to 256 solutions can be flagged. Thus, a solution will be flagged if the corresponding bit is 1. LSB first.
  • blockNumber the starting point.

finalizeSolution() returns ()


Finalize solution and move to the next block. This must happen in block order. Nothing can be finalized if a challenge is still active. and cannot happen if there is an active challenge. calldata layout: | 4 byte function sig | | 32 byte block number | --- | 32 byte length of solution | | solution... | --- | repeat above (---) |

finalizedHeight() returns (uint256 ret)


Returns the highest finalized block.

onChallenge() returns (uint256)


Challenge the solution or just verify the next pending block directly. calldata layout: | 4 bytes function sig | | 32 bytes challenge offset | | 32 bytes address of challenge handler - contract (self) | | 32 bytes size of block | | 32 bytes number of challenge rounds | | arbitrary witness data | | data of block |

onClaimUsername(address msgSender, uint256 nonce, bytes32 shortString) returns ()


State transition when a user claims a (short) username. Only one username can be claimed for msgSender. If msgSender already claimed a name, then it should be freed.

onCreateCommunity(address msgSender, uint256 nonce, address governanceToken, bytes metadata) returns ()


Creates a Habitat Community.

onCreateProposal(address msgSender, uint256 nonce, uint256 startDate, address vault, bytes internalActions, bytes externalActions, bytes metadata) returns ()


Creates a proposal belonging to vault.

  • externalActions includes L1 specific actions if this proposal passes. (execution permit)
  • internalActions includes L2 specific actions if this proposal passes.
  • startDate Should be within a reasonable range. See _PROPOSAL_DELAY

onCreateVault(address msgSender, uint256 nonce, bytes32 communityId, address condition, bytes metadata) returns ()


Creates a Habitat Vault for a Community.

onCreateVirtualERC20(address msgSender, uint256 nonce, address factoryAddress, bytes args) returns ()


User invokable state transition.

onDelegateAmount(address msgSender, uint256 nonce, address delegatee, address token, uint256 newAllowance) returns ()


State transition when a user sets a delegate.

onDeposit(address owner, address token, uint256 value, uint256 tokenType) returns ()


State transition when a user deposits a token.

onFinalizeSolution(uint256, bytes32 hash) returns ()


Finalize solution for blockNumber and move to the next block. Calldata(data appended at the end) contains a blob of key:value pairs that go into storage. If this functions reverts, then the block can only be finalised by a call to challenge. - Should only be callable from self. - Supports relative value(delta) and absolute storage updates calldata layout: | 4 byte function sig | | 32 byte blockNumber | | 32 byte submitted solution hash | | witness data |

onProcessProposal(address msgSender, uint256 nonce, bytes32 proposalId, bytes internalActions, bytes externalActions) returns (uint256 votingStatus, uint256 secondsTillClose, uint256 quorumPercent)


Updates the state of a proposal.

Only emits a event if the status changes to CLOSED or PASSED

onTransferToken(address msgSender, uint256 nonce, address token, address to, uint256 value) returns ()


State transition when a user transfers a token.

onVoteOnProposal(address msgSender, uint256 nonce, bytes32 proposalId, uint256 shares, address delegatee, uint8 signalStrength) returns ()


State transition routine for VoteOnProposal. Note: Votes can be changed/removed anytime.

pendingHeight() returns (uint256 ret)


Highest not finalized block

registerModule(uint256 _type, address contractAddress, bytes32 codeHash, bytes) returns ()


Register a module to be used for Habitat Vaults (Treasuries). The bytecode at contractAddress must apply to some conventions, see _verifyModule.

  • _type Must be 1.
  • codeHash of the bytecode @ contractAddress
  • contractAddress of the module.

submitBlock() returns ()


Submit a transaction blob (a block). The block data is expected right after the 4-byte function signature. Only regular accounts are allowed to submit blocks.

submitSolution() returns ()


Register solution for given blockNumber. Up to 256 solutions can be registered ahead in time. calldata layout: |4 byte function sig| |32 bytes number of first block| |32 bytes for each solution for blocks starting at first block (increments by one)| Note: You can put holes in the layout by inserting a 32 byte zero value. Only regular accounts are allowed to submit solutions.

withdraw(address owner, address token, uint256 tokenId) returns ()


Withdraw token and tokenId from bridge. tokenId is ignored if token is not a ERC-721.

  • owner address of the account to withdraw from and to.
  • token address of the token.
  • tokenId ERC-721 token id.



Add multiplicator parameter that says: if any N blocks get flagged, then increase the INSPECTION_PERIOD times INSPECTION_PERIOD_MULTIPLIER that puts the possible inspection period for these blocks higher up so that operators and chain users can cooperate on any situation within a bigger timeframe. That means if someone wrongfully flags valid solutions for blocks, then this just increases the INSPECTION_PERIOD and operators are not forced into challenges. If no one challenges any blocks within the increased timeframe, then the block(s) can be finalized as usual after the elevated INSPECTION_PERIOD.

ROLLUP_MANAGER() returns (address)


Returns the address who is in charge of changing the rollup implementation. This contract should be managed by a ExecutionProxy that in turn verifies governance decisions from the rollup. The rollup will be managed by a multisig in the beginning until moving to community governance. It should be noted that there should be a emergency contract on L1 that can be used to recover from bad upgrades in case the rollup is malfunctioning itself.

STAKING_POOL_FEE_DIVISOR() returns (uint256)


The divisor for every tribute. A fraction of the operator tribute always goes into the staking pool.

communityOfVault(address vault) returns (bytes32)


Returns the communityId of vault.

executionPermit(address vault, bytes32 proposalId) returns (bytes32 ret)


Execution permit for |vault, proposalId| = keccak256(actions).

getBalance(address tkn, address account) returns (uint256)


The token balance of tkn for `account. This works for ERC-20 and ERC-721.

getCurrentEpoch() returns (uint256)


Epoch should be greater than 0.

getErc721Owner(address tkn, uint256 b) returns (address)


Returns the owner of a ERC-721 token.

getProposalStatus(bytes32 a) returns (uint256)


Returns the voting status of proposal id a.

getTotalMemberCount(bytes32 communityId) returns (uint256)


Returns the member count for communityId. An account automatically becomes a member if it interacts with community vaults & proposals.

getTotalVotingShares(bytes32 proposalId) returns (uint256)


Returns the cumulative voted shares on proposalId.

getUnlockedBalance(address token, address account) returns (uint256 ret)


Returns the (free) balance (amount of token) for account. Free = balance of token for account - activeVotingStake & delegated stake for account. Supports ERC-20 and ERC-721 and takes staked balances into account.

onClaimStakingReward(address msgSender, uint256 nonce, address token, uint256 sinceEpoch) returns ()


Claims staking rewards for epoch.

onCustomBlockBeacon(bytes data) returns ()


Layer 2 callback for blocks created with _createBlockMessage. Used for module registration (type = 1).

onModifyRollupStorage(address msgSender, uint256 nonce, bytes data) returns ()


Used for fixing rollup storage due to logic bugs.

onTributeForOperator(address msgSender, uint256 nonce, address operator, address token, uint256 amount) returns ()


Transfers funds to a (trusted) operator. A fraction STAKING_POOL_FEE_DIVISOR of the funds goes to the staking pool.

tokenOfCommunity(bytes32 a) returns (address)


Governance Token of community.

txNonces(address a) returns (uint256)


The nonce of account a.

upgradeRollup(address newImplementation) returns ()


Upgrades the implementation.