Synopsis

Automatically generated reference documentation of the smart-contract method

Technical Specification

List of the contract functions and variables.

NOCUSTCommitChain

This is the main Parent-chain Verifier contract. It inherits all of the proxy contracts and provides a single address to interact with all the moderated balance pools. Proxies define the exposed methods, events and enforce the modifiers of library methods.

constructor(uint256 blocksPerEon, address operator)

Main constructor

blocksPerEon Eon interval in blocks operator Operator's address

registerERC20(contract ERC20 token)

This allows the operator to register the existence of another ERC20 token

token ERC20 token contract address

submitCheckpoint(bytes32 accumulator, bytes32 merkleRoot)

Submit checkpoint of eon

accumulator Last hash of the accumulator chain of on-chain events merkleRoot Checkpoint hash

BimodalProxy

Specify the data structures of the bimodal that needs to be stored on chain. Define all events, modifiers and the bimodal ledger itself.

constructor(uint256 blocksPerEon, address operator)

Constructor

blocksPerEon Eon interval in blocks operator Operator's address

getClientContractStateVariables(contract ERC20 token, address holder)

Get all the variables required for an account in a single-shot

token Token of the account holder Address of the account

getServerContractStateVariables()

Get all the contract constants needed for the operator in a single-shot

getServerContractLedgerStateVariables(uint256 eonNumber, contract ERC20 token)

Get the ledger state for a specific token

hasOutstandingChallenges()

If there is any pending challenges

hasMissedCheckpointSubmission()

If a checkpoint was missed

getCheckpointAtSlot(uint8 slot)

Get one of the latest checkpoint

slot Slot of the checkpoint to get. Slot equals to eonNumber mod EONS_KEPT

getParentChainAccumulatorAtSlot(uint8 slot)

Get one of the latest chain accumulator

slot Slot of the checkpoint to get the accumulator. Slot equals to eonNumber mod EONS_KEPT

getChallenge(contract ERC20 token, address sender, address recipient)

Get the details of a specific challenge

token Token of the account challenged sender Initiator of the challenge recipient Target of the challenge, if equals to sender this is a state update challenge

getIsWalletRecovered(contract ERC20 token, address holder)

To know if a wallet was emptied after entering recovery mode

token Token address holder Account address

getDepositsAtEon(contract ERC20 token, address addr, uint256 eon)

Get the deposits of a specific account during a specific eon

addr Account address eon Eon number

getDepositsAtSlot(contract ERC20 token, uint8 slot)

Get all deposits of a specific token

token Token address slot Slot of the eon

getWalletDepositAggregateAtSlot(contract ERC20 token, address addr, uint8 slot)

Get deposits of an account at slot

token Token address addr Account address slot Slot of the eon

getPendingWithdrawalsAtEon(contract ERC20 token, uint256 eon)

Get all pending withdrawal of a token

eon Eon number

getPendingWithdrawalsAtSlot(contract ERC20 token, uint8 slot)

Get all pending withdrawal at slot

token Token address slot Slot of the eon

getConfirmedWithdrawalsAtSlot(contract ERC20 token, uint8 slot)

Get all confirmed withdrawal at slot

token Token address slot Slot of the eon

getWalletPendingWithdrawalAmountAtEon(contract ERC20 token, address holder, uint256 eon)

Get pending withdrawals of a specific account during a specific eon

holder Account address eon Eon number

getTokenTrail(contract ERC20 token)

Get the leaf index of a token in the membership tree

token Token address

getTokenAtTrail(uint64 trail)

Get the token address of an index leaf in the membership tree

token Leaf index in the membership tree

getCurrentEonDepositsWithdrawals(contract ERC20 token, address holder)

Get the number of deposit and withdrawal made in the current eon

token Token Address holder Account address

EONS_KEPT()

Number of recent eons to keep in memory

DEPOSITS_KEPT()

Number of recent deposits to keep in memory

MIN_CHALLENGE_GAS_COST()

Minimum gas price that will be considered for the challenge subsidy

BLOCKS_PER_EON()

Eon length in blocks

BLOCKS_PER_EPOCH()

Epoch length in blocks

EXTENDED_BLOCKS_PER_EPOCH()

Extended epoch length in blocks

genesis()

Block number of the contract creation

operator()

Operator's address

lastSubmissionEon()

number of the last submitted eon

currentEon()

number of the current eon (!= lastSubmissionEon because we might not have submitted the checkpoint yet)

currentEra()

number of the current era

getLiveChallenges(uint256 eon)

number of live/pending challenges

Eon number

signedMessageECRECOVER(bytes32 message, bytes32 r, bytes32 s, uint8 v)

Verify a signature with NOCUST and Ethereum wrapper

message hash of the message r Element of the signature s Element of the signature v Element of the signature

onlyOperator()

Only operator modifier

onlyWhenContractUnpunished()

Only when the contract is not in recovery modifier

CheckpointSubmission(uint256 eon, bytes32 merkleRoot)

Emitted when a checkpoint is submitted

eon Eon number merkleRoot Checkpoint root hash

Deposit(address token, address recipient, uint256 amount)

Emitted when someone deposits

token Token deposited recipient Recipient of the deposit amount Amount of the deposit

WithdrawalRequest(address token, address requestor, uint256 amount)

Emitted when someone make a withdrawal request

token Token of the request requestor User making the request amount Amount of the withdrawal

WithdrawalConfirmation(address token, address requestor, uint256 amount)

Emitted when a withdrawal is confirmed

token Token of the request requestor User making the request amount Amount of the withdrawal

ChallengeIssued(address token, address recipient, address sender)

Emitted when someone initiate a challenge

token Token of the account challenged recipient Target of the challenge, if equals to sender this is a state update challenge sender Initiator of the challenge

StateUpdate(address token, address account, uint256 eon, uint64 trail, bytes32[] allotmentChain, bytes32[] membershipChain, uint256[] values, uint256[2][3] lrDeltasPassiveMark, bytes32 activeStateChecksum, bytes32 passiveChecksum, bytes32 r, bytes32 s, uint8 v)

Emitted when a state update challenge is answered

token Token of the challenge account Challenged account eon Eon number trail Leaf index on the challenged account allotmentChain Merkle path in the allotment tree of the token of the challenge membershipChain Merkle path in the membership interval tree of the account of the challenge values Values along the Merkle path of the membership interval tree lrDeltasPassiveMark Variable from the account aggregate and active state: [ [Left value, Right value], [Gained, Spent], [passive received, passive marker] ] activeStateChecksum Active state hash passiveChecksum Passive tree checksum r Element of the operator signature s Element of the operator signature v Element of the operator signature

ChallengeProxy

verifyProofOfExclusiveAccountBalanceAllotment(contract ERC20 token, address holder, bytes32[2] activeStateChecksum_passiveTransfersRoot, uint64 trail, uint256[3] eonPassiveMark, bytes32[] allotmentChain, bytes32[] membershipChain, uint256[] values, uint256[2] LR)

Verify a proof of exclusive allotment of a user account and active state from the checkpoint available on the parent chain down to the user account for a specific token

token ERC20 token address or contract address for Ether holder Account address activeStateChecksum_passiveTransfersRoot Array containing [ Active state checksum, Root of the passive tree] trail Account leaf index eonPassiveMark Array containing [ Eon number, Passive received amount, Passive marker] allotment allotmentChain Merkle path in the allotment tree of the token of the challenge membershipChain Merkle path in the membership interval tree of the account of the challenge LR Array containing the values [ Left, Right] of the account

verifyProofOfActiveStateUpdateAgreement(contract ERC20 token, address holder, uint64 trail, uint256 eon, bytes32 txSetRoot, uint256[2] deltas, address attester, bytes32 r, bytes32 s, uint8 v)

Function used to verify the validity of an active state including signature verification

token ERC20 token address or contract address for Ether holder Account address of the active state trail Leaf index of the account in the account tree eon Eon number of the active state txSetRoot Merkle Root of the active tree deltas Array containing the values [Spent, Gained] of the active state r Element of the operator signature s Element of the operator signature v Element of the operator signature

verifyWithdrawalAuthorization(contract ERC20 token, address holder, uint256 expiry, uint256 amount, address attester, bytes32 r, bytes32 s, uint8 v)

Verify a withdrawal authorization from an attester (User or operator)

token ERC20 token address or contract address for Ether holder Account making the withdrawal expiry Expiration block number of the withdrawal authorization. amount Withdrawal amount r Element of the operator signature s Element of the operator signature v Element of the operator signature

verifyProofOfExclusiveBalanceAllotment(uint64 allotmentTrail, uint64 membershipTrail, bytes32 node, bytes32 root, bytes32[] allotmentChain, bytes32[] membershipChain, uint256[] value, uint256[2] LR)

Verify a proof of exclusive allotment of an account without recalculating the active state

allotmentTrail Leaf index in the account tree membershipTrail Leaf index in the membership tree (token trail) node Leaf, the active state checksum root Checkpoint on the parent-chain allotmentChain Merkle path in the allotment tree of the token of the challenge membershipChain Merkle path in the membership interval tree of the account of the challenge value Values along the Merkle path of the membership interval tree

verifyProofOfMembership(uint256 trail, bytes32[] chain, bytes32 node, bytes32 merkleRoot)

Verify a proof of membership for the active tree

trail leaf index of the transfer chain Merkle proof node Transfer checksum merkleRoot Active tree checksum

verifyProofOfPassiveDelivery(uint64 allotmentTrail, bytes32 node, bytes32 root, bytes32[] chainValues, uint256[2] LR)

Verify a proof of membership for a passive tree (passive transfer tree)

allotmentTrail leaf index of the transfer node Transfer checksum root Passive tree checksum chainValues Values along the interval tree proof LR Left and right value of the leaf

challengeStateUpdateWithProofOfExclusiveBalanceAllotment(contract ERC20 token, bytes32[2] checksums, uint64 trail, bytes32[] allotmentChain, bytes32[] membershipChain, uint256[] value, uint256[2][3] lrDeltasPassiveMark, bytes32[3] rsTxSetRoot, uint8 v)

Initiate a state update balance challenge for account created before the previous round

token ERC20 token address or contract address for Ether checksums Array containing [ Active state checksum, Root of the passive tree] trail Account leaf index allotmentChain Merkle path in the allotment tree of the token of the challenge membershipChain Merkle path in the membership interval tree of the account of the challenge value Values along the Merkle path of the membership interval tree lrDeltasPassiveMark Variable from the account aggregate and active state: [ [Left value, Right value], [Gained, Spent], [passive received, passive marker] ] rsTxSetRoot Array containing [R value of the operator signature of the active state, S value of the operator signature of the active state, active tree root (again)] v V value of the signature

challengeStateUpdateWithProofOfActiveStateUpdateAgreement(contract ERC20 token, bytes32 txSetRoot, uint64 trail, uint256[2] deltas, bytes32 r, bytes32 s, uint8 v)

Initiate a state update challenge for account created in the previous round

token ERC20 token address or contract address for Ether txSetRoot Active tree root trail Leaf index of the account deltas [Spent,Gained] values of the account r Element of the operator signature s Element of the operator signature v Element of the operator signature

answerStateUpdateChallenge(contract ERC20 token, address issuer, bytes32[] allotmentChain, bytes32[] membershipChain, uint256[] values, uint256[2][3] lrDeltasPassiveMark, bytes32[6] rSrStxSetRootChecksum, uint8[2] v)

Function for the operator to answer state update challenge from a user

token ERC20 token address or contract address for Ether issuer Address of the account challenging allotmentChain Merkle path in the allotment tree of the token of the challenge membershipChain Merkle path in the membership interval tree of the account of the challenge values Values along the Merkle path of the membership interval tree lrDeltasPassiveMark Variable from the account aggregate and active state: [ [Left value, Right value], [Gained, Spent], [passive received, passive marker] ] rSrStxSetRootChecksum Array containing the values [R value of the user signature, S value of the user signature, R value of the operator signature, S value of the operator signature, Active tree root, Passive tree root] v Array containing the values [V value of the user signature, V value of the operator signature]

challengeTransferDeliveryWithProofOfActiveStateUpdateAgreement(contract ERC20 token, address[2] SR, uint256[2] nonceAmount, uint64[3] trails, bytes32[] chain, uint256[2] deltas, bytes32[3] rsTxSetRoot, uint8 v)

To challenge delivery for non finalized transfers (last in recipient passive set)

token ERC20 token address or contract address for Ether SR [Sender, Recipient] of the challenged transfer nonceAmount [Nonce of the transfer, Amount of the transfer] trails Leaf index of the transfer chain Proof in the active tree deltas [Gained, Spent] values of the active state rsTxSetRoot Array containing [R value of the operator signature of the active state, S value of the operator signature of the active state, active tree root (again)] v V value of the operator signature

answerTransferDeliveryChallengeWithProofOfActiveStateUpdateAgreement(contract ERC20 token, address[2] SR, uint64 transferMembershipTrail, bytes32[] allotmentChain, bytes32[] membershipChain, uint256[] values, uint256[2][3] lrDeltasPassiveMark, bytes32[2] txSetRootChecksum, bytes32[] txChain)

To answer challenge delivery for non finalized transfers (last in recipient passive set)

token ERC20 token address or contract address for Ether SR [Sender, Recipient] of the challenged transfer transferMembershipTrail Transfer leaf index allotmentChain Merkle path in the allotment tree of the token of the challenge membershipChain Merkle path in the membership interval tree of the account of the challenge values Values along the Merkle path of the membership interval tree lrDeltasPassiveMark Variable from the account aggregate and active state: [ [Left value, Right value], [Gained, Spent], [passive received, passive marker] ] txSetRootChecksum Array containing [Active tree root, Passive tree root] txChain Merkle proof of the transfer in the active tree

challengeTransferDeliveryWithProofOfPassiveStateUpdate(contract ERC20 token, address[2] SR, bytes32[2] txSetRootChecksum, uint64[3] senderTransferRecipientTrails, bytes32[] allotmentChain, bytes32[] membershipChain, uint256[] values, uint256[2][4] lrDeltasPassiveMarkDummyAmount, bytes32[] transferMembershipChain)

To challenge delivery for finalized transfers

token ERC20 token address or contract address for Ether SR [Sender, Recipient] of the challenged transfer txSetRootChecksum Array containing [Active tree root, Passive tree root] allotmentChain Merkle path in the allotment tree of the token of the challenge membershipChain Merkle path in the membership interval tree of the account of the challenge values Values along the Merkle path of the membership interval tree lrDeltasPassiveMarkDummyAmount Array containing [ [Left, Right], [Spent, Gained], [Any value (does not matter), Amount of the transfer]] transferMembershipChain Merkle proof of the transfer at the sender

answerTransferDeliveryChallengeWithProofOfPassiveStateUpdate(contract ERC20 token, address[2] SR, uint64 transferMembershipTrail, bytes32[] allotmentChain, bytes32[] membershipChain, uint256[] values, uint256[2][3] lrPassiveMarkPositionNonce, bytes32[2] checksums, bytes32[] txChainValues)

To answer challenge delivery for finalized transfers

token ERC20 token address or contract address for Ether SR [Sender, Recipient] of the challenged transfer transferMembershipTrail Transfer leaf index of the recipient allotmentChain Merkle path in the allotment tree of the token of the challenge membershipChain Merkle path in the membership interval tree of the account of the challenge values Values along the Merkle path of the membership interval tree lrPassiveMarkPositionNonce Array containing [ [Left, Right], [Passive amount received, Passive marker], [Passive marker (again), Transfer nonce]] txChainValues Values along the passive tree Merkle proof in the recipient passive tree

challengeSwapEnactmentWithProofOfActiveStateUpdateAgreement(contract ERC20[2] tokens, uint64[3] senderTransferRecipientTrails, bytes32[] allotmentChain, bytes32[] membershipChain, bytes32[] txChain, uint256[] values, uint256[2][3] lrDeltasPassiveMark, uint256[4] sellBuyBalanceNonce, bytes32[3] txSetRootChecksumDummy)

To challenge swap fulfillment

token ERC20 token address or contract address for Ether senderTransferRecipientTrails Array containing [Selling leaf account index, Transfer leaf index in selling account's active tree, Buying account leaf index] allotmentChain Merkle path in the allotment tree of the token of the selling account membershipChain Merkle path in the membership interval tree of the selling account txChain Merkle proof of the transfer in the Selling account values Values along the Merkle path of the membership interval tree lrDeltasPassiveMark Variable from the account aggregate and active state from the selling account: [ [Left value, Right value], [Gained, Spent], [passive received, passive marker] ] sellBuyBalanceNonce Array containing [Sell amount, Buy amount, Nonce of the swap] txSetRootChecksumDummy Array containing [Root of the active tree at the selling account, Checksum of the swap, Any value]

answerSwapChallengeWithProofOfExclusiveBalanceAllotment(contract ERC20[2] tokens, address issuer, uint64 transferMembershipTrail, bytes32[] allotmentChain, bytes32[] membershipChain, bytes32[] txChain, uint256[] values, uint256[2][3] lrDeltasPassiveMark, uint256 balance, bytes32[3] txSetRootChecksumDummy)

To answer swap fulfillment challenge

token ERC20 token address or contract address for Ether issuer Challenge initiator address allotmentChain Merkle path in the allotment tree of the token of the buying account membershipChain Merkle path in the membership interval tree of the buying account txChain Merkle proof of the transfer in the buying account values Values along the Merkle path of the membership interval tree lrDeltasPassiveMark Variable from the account aggregate and active state of the buying account: [ [Left value, Right value], [Gained, Spent], [passive received, passive marker] ] balance Swap starting balance txSetRootChecksumDummy Array containing [Root of the active tree at the buying account, Checksum of the swap, Any value]

slashWithdrawalWithProofOfMinimumAvailableBalance(contract ERC20 token, address withdrawer, uint256[2] markerEonAvailable, bytes32[2] rs, uint8 v)

Slash a withdrawal attempting to over withdraw funds

token ERC20 token address or contract address for Ether withdrawer Withdrawal initiator markerEonAvailable Balance marker checksum rs [R value of the balance marker checksum, S value of the balance marker checksum] v V value of the balance marker checksum

onlyWithFairReimbursement()

Modifier used to enforce a user subsidy of the challenge answer

onlyWithSkewedReimbursement(uint256 extra)

Modifier used to enforce a user subsidy of the challenge answer

DepositProxy

fallback()

Function called when no public function where found on the contract. Does nothing, the contract is still credited if some Ether is attached.

deposit(contract ERC20 token, address beneficiary, uint256 amount)

Deposit funds, Ether or ERC20 tokens into the commit-chain. Be sure to send the corresponding amount of Ether with the function call is depositing Ether. If depositing ERC20 be sure to have sufficient balance AND that the NOCUST contract is authorized to transfer this amount of funds through the approve function of the ERC20 contract.

token ERC20 token address of the asset to deposit. If Ether, this field should be equal to the NOCUST contract address beneficiary Account to credit the deposit amount Amount of funds to deposit. Should match the amount of Ether attached to the transaction (if depositing Ether). If depositing ERC20 be sure that the NOCUST smart-contract address can transfer the corresponding amount of funds.

MerkleVerifierProxy

calculateMerkleRoot(uint256 trail, bytes32[] chain, bytes32 node)

Calculate the Merkle root for a standard Merkle tree given a Merkle proof

trail Leaf index of the Merkle tree chain Merkle path node Leaf hash

verifyProofOfExclusiveBalanceAllotment(uint64 allotmentTrail, uint64 membershipTrail, bytes32 node, bytes32 root, bytes32[] allotmentChain, bytes32[] membershipChain, uint256[] value, uint256[2] LR)

Verify the Merkle proof of an interval tree

allotmentTrail Leaf index in the account tree membershipTrail Leaf index in the membership tree (token trail) node Leaf checksum root Parent Root Checkpoint/commitment allotmentChain Transfer leaf index of the account membershipChain Merkle path in the allotment tree of the token of the account value Values along the Merkle path of the membership interval tree LR Left and right values of the leaf account

verifyProofOfPassiveDelivery(uint64 allotmentTrail, bytes32 node, bytes32 root, bytes32[] chainValues, uint256[2] LR)

Verify the interval tree proof of a transfer in the the passive tree

allotmentTrail Leaf account of the transfer node Transfer checksum root Passive tree root chainValues Values along the interval tree proof LR Left and right values of the leaf transfer

transferChecksum(address counterparty, uint256 amount, uint64 recipientTrail, uint256 nonce)

Calculate the checksum of a transfer. A transfer checksum depends if the checksum to be used is in the recipient and sender account.

counterparty Counter party of the transfer (recipient or sender depending on the location of the transfer) amount Amount of the transfer recipientTrail Leaf index of the recipient account in the account tree nonce Nonce of the transfer

swapOrderChecksum(contract ERC20[2] tokens, uint64 recipientTrail, uint256 sellAmount, uint256 buyAmount, uint256 startBalance, uint256 nonce)

Calculate the checksum of a swap transaction

tokens Token addresses of the swap [sellTokenAddress, buyTokenAddress] recipientTrail Leaf index of the buy account in the account tree of the buy token sellAmount Amount of token to sell buyAmount Amount of token to buy startBalance Balance of the buy account be for the swap nonce Nonce of the swap

activeStateUpdateChecksum(contract ERC20 token, address holder, uint64 trail, uint256 eon, bytes32 txSetRoot, uint256[2] deltas)

Calculate an active-state checksum

token Account token holder Account address trail Leaf index in the account tree eon Eon number txSetRoot Merkle root of the active-tree deltas [Spent, Gained]

RecoveryProxy

recoverOnlyParentChainFunds(contract ERC20 token, address holder)

When the commit-chain is in recovery this function allows an address to recover funds from unfinished withdrawals and funds deposited in the previous round

token Token to recover holder Address of the funds to recover

recoverAllFunds(contract ERC20 token, address holder, bytes32[2] checksums, uint64 trail, bytes32[] allotmentChain, bytes32[] membershipChain, uint256[] values, uint256[2] LR, uint256[3] dummyPassiveMark)

Require a proof of exclusive allotment. When the commit-chain is in recovery this function recovers all of the commit-chain balance and pending withdrawals

token Token address of the account to recover checksums Array containing [Active State checksum, passive tree Checksum] trail Leaf index of the account to recover allotmentChain Merkle path in the allotment tree of the token of the account to recover membershipChain Merkle path in the membership interval tree of the account to recover value Values along the Merkle path of the membership interval tree LR Left and right values of the account in the account interval tree dummyPassiveMark Array containing [Any value (does not matter), Passive amount received, Passive marker]

onlyWhenContractPunished()

Modifier to ensure that the contract is not in recovery

WithdrawalProxy

requestWithdrawal(contract ERC20 token, bytes32[2] checksums, uint64 trail, bytes32[] allotmentChain, bytes32[] membershipChain, uint256[] values, uint256[2][2] lrPassiveMark, uint256 withdrawalAmount)

Initiate a unilateral withdrawal with a Proof of exclusive allotment

token Token address of the account to recover checksums Array containing [Active State checksum, passive tree Checksum] trail Leaf index of the account to recover allotmentChain Merkle path in the allotment tree of the token of the account to withdraw from membershipChain Merkle path in the membership interval tree of the account to withdraw from value Values along the Merkle path of the membership interval tree lrPassiveMark Array container the values [ [ Left value, Right value], [Passive amount received, Passive marker] ] dummyPassiveMark Amount to withdraw from the commit-chain account

requestAuthorizedWithdrawal(contract ERC20 token, uint256 withdrawalAmount, uint256 expiry, bytes32 r, bytes32 s, uint8 v)

Alternate withdrawal method by providing the operator's approval signature

token Token address of the withdrawal withdrawalAmount Amount to withdraw expiry Expiry block of until when the withdrawal can be initiated r Element of the operator approval signature s Element of the operator approval signature v Element of the operator approval signature

requestDelegatedWithdrawal(contract ERC20 token, address holder, uint256 withdrawalAmount, uint256 expiry, bytes32 r, bytes32 s, uint8 v)

Alternate withdrawal method which allow the operator to initiate a withdrawal given the account owner approval signature

token Token address of the withdrawal holder Account of the withdrawal withdrawalAmount Amount to withdraw expiry Expiry block of until when the withdrawal can be initiated r Element of the user approval signature s Element of the user approval signature v Element of the user approval signature

confirmWithdrawal(contract ERC20 token, address recipient)

Finalize a withdrawal and effectively transfer the fund to the on-chain account after the clearing period. It will confirm all pending withdrawals for a given account.

token Token address of the account recipient Withdrawing account

onlyWithConstantReimbursement(uint256 responseGas)

Enforce the withdrawal subsidy used to cover potential cost of slashing the withdrawal. The user has to pay for 100100 units of gas at the price of the withdrawal request with a minimum of 10 Gwei.

History

  • 10.09.2019 Initial generation
  • 09.12.2019 Add doc from inline documentation

All content herein is licensed under GPL License.

results matching ""

    No results matching ""