diff --git a/solidity/deployments/mainnet/solcInputs/7c1f8f1dbded4c787d87a982d1fc8349.json b/solidity/deployments/mainnet/solcInputs/7c1f8f1dbded4c787d87a982d1fc8349.json new file mode 100644 index 000000000..dcf47c5d8 --- /dev/null +++ b/solidity/deployments/mainnet/solcInputs/7c1f8f1dbded4c787d87a982d1fc8349.json @@ -0,0 +1,410 @@ +{ + "language": "Solidity", + "sources": { + "@keep-network/bitcoin-spv-sol/contracts/BTCUtils.sol": { + "content": "pragma solidity ^0.8.4;\n\n/** @title BitcoinSPV */\n/** @author Summa (https://summa.one) */\n\nimport {BytesLib} from \"./BytesLib.sol\";\nimport {SafeMath} from \"./SafeMath.sol\";\n\nlibrary BTCUtils {\n using BytesLib for bytes;\n using SafeMath for uint256;\n\n // The target at minimum Difficulty. Also the target of the genesis block\n uint256 public constant DIFF1_TARGET = 0xffff0000000000000000000000000000000000000000000000000000;\n\n uint256 public constant RETARGET_PERIOD = 2 * 7 * 24 * 60 * 60; // 2 weeks in seconds\n uint256 public constant RETARGET_PERIOD_BLOCKS = 2016; // 2 weeks in blocks\n\n uint256 public constant ERR_BAD_ARG = 0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff;\n\n /* ***** */\n /* UTILS */\n /* ***** */\n\n /// @notice Determines the length of a VarInt in bytes\n /// @dev A VarInt of >1 byte is prefixed with a flag indicating its length\n /// @param _flag The first byte of a VarInt\n /// @return The number of non-flag bytes in the VarInt\n function determineVarIntDataLength(bytes memory _flag) internal pure returns (uint8) {\n return determineVarIntDataLengthAt(_flag, 0);\n }\n\n /// @notice Determines the length of a VarInt in bytes\n /// @dev A VarInt of >1 byte is prefixed with a flag indicating its length\n /// @param _b The byte array containing a VarInt\n /// @param _at The position of the VarInt in the array\n /// @return The number of non-flag bytes in the VarInt\n function determineVarIntDataLengthAt(bytes memory _b, uint256 _at) internal pure returns (uint8) {\n if (uint8(_b[_at]) == 0xff) {\n return 8; // one-byte flag, 8 bytes data\n }\n if (uint8(_b[_at]) == 0xfe) {\n return 4; // one-byte flag, 4 bytes data\n }\n if (uint8(_b[_at]) == 0xfd) {\n return 2; // one-byte flag, 2 bytes data\n }\n\n return 0; // flag is data\n }\n\n /// @notice Parse a VarInt into its data length and the number it represents\n /// @dev Useful for Parsing Vins and Vouts. Returns ERR_BAD_ARG if insufficient bytes.\n /// Caller SHOULD explicitly handle this case (or bubble it up)\n /// @param _b A byte-string starting with a VarInt\n /// @return number of bytes in the encoding (not counting the tag), the encoded int\n function parseVarInt(bytes memory _b) internal pure returns (uint256, uint256) {\n return parseVarIntAt(_b, 0);\n }\n\n /// @notice Parse a VarInt into its data length and the number it represents\n /// @dev Useful for Parsing Vins and Vouts. Returns ERR_BAD_ARG if insufficient bytes.\n /// Caller SHOULD explicitly handle this case (or bubble it up)\n /// @param _b A byte-string containing a VarInt\n /// @param _at The position of the VarInt\n /// @return number of bytes in the encoding (not counting the tag), the encoded int\n function parseVarIntAt(bytes memory _b, uint256 _at) internal pure returns (uint256, uint256) {\n uint8 _dataLen = determineVarIntDataLengthAt(_b, _at);\n\n if (_dataLen == 0) {\n return (0, uint8(_b[_at]));\n }\n if (_b.length < 1 + _dataLen + _at) {\n return (ERR_BAD_ARG, 0);\n }\n uint256 _number;\n if (_dataLen == 2) {\n _number = reverseUint16(uint16(_b.slice2(1 + _at)));\n } else if (_dataLen == 4) {\n _number = reverseUint32(uint32(_b.slice4(1 + _at)));\n } else if (_dataLen == 8) {\n _number = reverseUint64(uint64(_b.slice8(1 + _at)));\n }\n return (_dataLen, _number);\n }\n\n /// @notice Changes the endianness of a byte array\n /// @dev Returns a new, backwards, bytes\n /// @param _b The bytes to reverse\n /// @return The reversed bytes\n function reverseEndianness(bytes memory _b) internal pure returns (bytes memory) {\n bytes memory _newValue = new bytes(_b.length);\n\n for (uint i = 0; i < _b.length; i++) {\n _newValue[_b.length - i - 1] = _b[i];\n }\n\n return _newValue;\n }\n\n /// @notice Changes the endianness of a uint256\n /// @dev https://graphics.stanford.edu/~seander/bithacks.html#ReverseParallel\n /// @param _b The unsigned integer to reverse\n /// @return v The reversed value\n function reverseUint256(uint256 _b) internal pure returns (uint256 v) {\n v = _b;\n\n // swap bytes\n v = ((v >> 8) & 0x00FF00FF00FF00FF00FF00FF00FF00FF00FF00FF00FF00FF00FF00FF00FF00FF) |\n ((v & 0x00FF00FF00FF00FF00FF00FF00FF00FF00FF00FF00FF00FF00FF00FF00FF00FF) << 8);\n // swap 2-byte long pairs\n v = ((v >> 16) & 0x0000FFFF0000FFFF0000FFFF0000FFFF0000FFFF0000FFFF0000FFFF0000FFFF) |\n ((v & 0x0000FFFF0000FFFF0000FFFF0000FFFF0000FFFF0000FFFF0000FFFF0000FFFF) << 16);\n // swap 4-byte long pairs\n v = ((v >> 32) & 0x00000000FFFFFFFF00000000FFFFFFFF00000000FFFFFFFF00000000FFFFFFFF) |\n ((v & 0x00000000FFFFFFFF00000000FFFFFFFF00000000FFFFFFFF00000000FFFFFFFF) << 32);\n // swap 8-byte long pairs\n v = ((v >> 64) & 0x0000000000000000FFFFFFFFFFFFFFFF0000000000000000FFFFFFFFFFFFFFFF) |\n ((v & 0x0000000000000000FFFFFFFFFFFFFFFF0000000000000000FFFFFFFFFFFFFFFF) << 64);\n // swap 16-byte long pairs\n v = (v >> 128) | (v << 128);\n }\n\n /// @notice Changes the endianness of a uint64\n /// @param _b The unsigned integer to reverse\n /// @return v The reversed value\n function reverseUint64(uint64 _b) internal pure returns (uint64 v) {\n v = _b;\n\n // swap bytes\n v = ((v >> 8) & 0x00FF00FF00FF00FF) |\n ((v & 0x00FF00FF00FF00FF) << 8);\n // swap 2-byte long pairs\n v = ((v >> 16) & 0x0000FFFF0000FFFF) |\n ((v & 0x0000FFFF0000FFFF) << 16);\n // swap 4-byte long pairs\n v = (v >> 32) | (v << 32);\n }\n\n /// @notice Changes the endianness of a uint32\n /// @param _b The unsigned integer to reverse\n /// @return v The reversed value\n function reverseUint32(uint32 _b) internal pure returns (uint32 v) {\n v = _b;\n\n // swap bytes\n v = ((v >> 8) & 0x00FF00FF) |\n ((v & 0x00FF00FF) << 8);\n // swap 2-byte long pairs\n v = (v >> 16) | (v << 16);\n }\n\n /// @notice Changes the endianness of a uint24\n /// @param _b The unsigned integer to reverse\n /// @return v The reversed value\n function reverseUint24(uint24 _b) internal pure returns (uint24 v) {\n v = (_b << 16) | (_b & 0x00FF00) | (_b >> 16);\n }\n\n /// @notice Changes the endianness of a uint16\n /// @param _b The unsigned integer to reverse\n /// @return v The reversed value\n function reverseUint16(uint16 _b) internal pure returns (uint16 v) {\n v = (_b << 8) | (_b >> 8);\n }\n\n\n /// @notice Converts big-endian bytes to a uint\n /// @dev Traverses the byte array and sums the bytes\n /// @param _b The big-endian bytes-encoded integer\n /// @return The integer representation\n function bytesToUint(bytes memory _b) internal pure returns (uint256) {\n uint256 _number;\n\n for (uint i = 0; i < _b.length; i++) {\n _number = _number + uint8(_b[i]) * (2 ** (8 * (_b.length - (i + 1))));\n }\n\n return _number;\n }\n\n /// @notice Get the last _num bytes from a byte array\n /// @param _b The byte array to slice\n /// @param _num The number of bytes to extract from the end\n /// @return The last _num bytes of _b\n function lastBytes(bytes memory _b, uint256 _num) internal pure returns (bytes memory) {\n uint256 _start = _b.length.sub(_num);\n\n return _b.slice(_start, _num);\n }\n\n /// @notice Implements bitcoin's hash160 (rmd160(sha2()))\n /// @dev abi.encodePacked changes the return to bytes instead of bytes32\n /// @param _b The pre-image\n /// @return The digest\n function hash160(bytes memory _b) internal pure returns (bytes memory) {\n return abi.encodePacked(ripemd160(abi.encodePacked(sha256(_b))));\n }\n\n /// @notice Implements bitcoin's hash160 (sha2 + ripemd160)\n /// @dev sha2 precompile at address(2), ripemd160 at address(3)\n /// @param _b The pre-image\n /// @return res The digest\n function hash160View(bytes memory _b) internal view returns (bytes20 res) {\n // solium-disable-next-line security/no-inline-assembly\n assembly {\n pop(staticcall(gas(), 2, add(_b, 32), mload(_b), 0x00, 32))\n pop(staticcall(gas(), 3, 0x00, 32, 0x00, 32))\n // read from position 12 = 0c\n res := mload(0x0c)\n }\n }\n\n /// @notice Implements bitcoin's hash256 (double sha2)\n /// @dev abi.encodePacked changes the return to bytes instead of bytes32\n /// @param _b The pre-image\n /// @return The digest\n function hash256(bytes memory _b) internal pure returns (bytes32) {\n return sha256(abi.encodePacked(sha256(_b)));\n }\n\n /// @notice Implements bitcoin's hash256 (double sha2)\n /// @dev sha2 is precompiled smart contract located at address(2)\n /// @param _b The pre-image\n /// @return res The digest\n function hash256View(bytes memory _b) internal view returns (bytes32 res) {\n // solium-disable-next-line security/no-inline-assembly\n assembly {\n pop(staticcall(gas(), 2, add(_b, 32), mload(_b), 0x00, 32))\n pop(staticcall(gas(), 2, 0x00, 32, 0x00, 32))\n res := mload(0x00)\n }\n }\n\n /// @notice Implements bitcoin's hash256 on a pair of bytes32\n /// @dev sha2 is precompiled smart contract located at address(2)\n /// @param _a The first bytes32 of the pre-image\n /// @param _b The second bytes32 of the pre-image\n /// @return res The digest\n function hash256Pair(bytes32 _a, bytes32 _b) internal view returns (bytes32 res) {\n // solium-disable-next-line security/no-inline-assembly\n assembly {\n mstore(0x00, _a)\n mstore(0x20, _b)\n pop(staticcall(gas(), 2, 0x00, 64, 0x00, 32))\n pop(staticcall(gas(), 2, 0x00, 32, 0x00, 32))\n res := mload(0x00)\n }\n }\n\n /// @notice Implements bitcoin's hash256 (double sha2)\n /// @dev sha2 is precompiled smart contract located at address(2)\n /// @param _b The array containing the pre-image\n /// @param at The start of the pre-image\n /// @param len The length of the pre-image\n /// @return res The digest\n function hash256Slice(\n bytes memory _b,\n uint256 at,\n uint256 len\n ) internal view returns (bytes32 res) {\n // solium-disable-next-line security/no-inline-assembly\n assembly {\n pop(staticcall(gas(), 2, add(_b, add(32, at)), len, 0x00, 32))\n pop(staticcall(gas(), 2, 0x00, 32, 0x00, 32))\n res := mload(0x00)\n }\n }\n\n /* ************ */\n /* Legacy Input */\n /* ************ */\n\n /// @notice Extracts the nth input from the vin (0-indexed)\n /// @dev Iterates over the vin. If you need to extract several, write a custom function\n /// @param _vin The vin as a tightly-packed byte array\n /// @param _index The 0-indexed location of the input to extract\n /// @return The input as a byte array\n function extractInputAtIndex(bytes memory _vin, uint256 _index) internal pure returns (bytes memory) {\n uint256 _varIntDataLen;\n uint256 _nIns;\n\n (_varIntDataLen, _nIns) = parseVarInt(_vin);\n require(_varIntDataLen != ERR_BAD_ARG, \"Read overrun during VarInt parsing\");\n require(_index < _nIns, \"Vin read overrun\");\n\n uint256 _len = 0;\n uint256 _offset = 1 + _varIntDataLen;\n\n for (uint256 _i = 0; _i < _index; _i ++) {\n _len = determineInputLengthAt(_vin, _offset);\n require(_len != ERR_BAD_ARG, \"Bad VarInt in scriptSig\");\n _offset = _offset + _len;\n }\n\n _len = determineInputLengthAt(_vin, _offset);\n require(_len != ERR_BAD_ARG, \"Bad VarInt in scriptSig\");\n return _vin.slice(_offset, _len);\n }\n\n /// @notice Determines whether an input is legacy\n /// @dev False if no scriptSig, otherwise True\n /// @param _input The input\n /// @return True for legacy, False for witness\n function isLegacyInput(bytes memory _input) internal pure returns (bool) {\n return _input[36] != hex\"00\";\n }\n\n /// @notice Determines the length of a scriptSig in an input\n /// @dev Will return 0 if passed a witness input.\n /// @param _input The LEGACY input\n /// @return The length of the script sig\n function extractScriptSigLen(bytes memory _input) internal pure returns (uint256, uint256) {\n return extractScriptSigLenAt(_input, 0);\n }\n\n /// @notice Determines the length of a scriptSig in an input\n /// starting at the specified position\n /// @dev Will return 0 if passed a witness input.\n /// @param _input The byte array containing the LEGACY input\n /// @param _at The position of the input in the array\n /// @return The length of the script sig\n function extractScriptSigLenAt(bytes memory _input, uint256 _at) internal pure returns (uint256, uint256) {\n if (_input.length < 37 + _at) {\n return (ERR_BAD_ARG, 0);\n }\n\n uint256 _varIntDataLen;\n uint256 _scriptSigLen;\n (_varIntDataLen, _scriptSigLen) = parseVarIntAt(_input, _at + 36);\n\n return (_varIntDataLen, _scriptSigLen);\n }\n\n /// @notice Determines the length of an input from its scriptSig\n /// @dev 36 for outpoint, 1 for scriptSig length, 4 for sequence\n /// @param _input The input\n /// @return The length of the input in bytes\n function determineInputLength(bytes memory _input) internal pure returns (uint256) {\n return determineInputLengthAt(_input, 0);\n }\n\n /// @notice Determines the length of an input from its scriptSig,\n /// starting at the specified position\n /// @dev 36 for outpoint, 1 for scriptSig length, 4 for sequence\n /// @param _input The byte array containing the input\n /// @param _at The position of the input in the array\n /// @return The length of the input in bytes\n function determineInputLengthAt(bytes memory _input, uint256 _at) internal pure returns (uint256) {\n uint256 _varIntDataLen;\n uint256 _scriptSigLen;\n (_varIntDataLen, _scriptSigLen) = extractScriptSigLenAt(_input, _at);\n if (_varIntDataLen == ERR_BAD_ARG) {\n return ERR_BAD_ARG;\n }\n\n return 36 + 1 + _varIntDataLen + _scriptSigLen + 4;\n }\n\n /// @notice Extracts the LE sequence bytes from an input\n /// @dev Sequence is used for relative time locks\n /// @param _input The LEGACY input\n /// @return The sequence bytes (LE uint)\n function extractSequenceLELegacy(bytes memory _input) internal pure returns (bytes4) {\n uint256 _varIntDataLen;\n uint256 _scriptSigLen;\n (_varIntDataLen, _scriptSigLen) = extractScriptSigLen(_input);\n require(_varIntDataLen != ERR_BAD_ARG, \"Bad VarInt in scriptSig\");\n return _input.slice4(36 + 1 + _varIntDataLen + _scriptSigLen);\n }\n\n /// @notice Extracts the sequence from the input\n /// @dev Sequence is a 4-byte little-endian number\n /// @param _input The LEGACY input\n /// @return The sequence number (big-endian uint)\n function extractSequenceLegacy(bytes memory _input) internal pure returns (uint32) {\n uint32 _leSeqence = uint32(extractSequenceLELegacy(_input));\n uint32 _beSequence = reverseUint32(_leSeqence);\n return _beSequence;\n }\n /// @notice Extracts the VarInt-prepended scriptSig from the input in a tx\n /// @dev Will return hex\"00\" if passed a witness input\n /// @param _input The LEGACY input\n /// @return The length-prepended scriptSig\n function extractScriptSig(bytes memory _input) internal pure returns (bytes memory) {\n uint256 _varIntDataLen;\n uint256 _scriptSigLen;\n (_varIntDataLen, _scriptSigLen) = extractScriptSigLen(_input);\n require(_varIntDataLen != ERR_BAD_ARG, \"Bad VarInt in scriptSig\");\n return _input.slice(36, 1 + _varIntDataLen + _scriptSigLen);\n }\n\n\n /* ************* */\n /* Witness Input */\n /* ************* */\n\n /// @notice Extracts the LE sequence bytes from an input\n /// @dev Sequence is used for relative time locks\n /// @param _input The WITNESS input\n /// @return The sequence bytes (LE uint)\n function extractSequenceLEWitness(bytes memory _input) internal pure returns (bytes4) {\n return _input.slice4(37);\n }\n\n /// @notice Extracts the sequence from the input in a tx\n /// @dev Sequence is a 4-byte little-endian number\n /// @param _input The WITNESS input\n /// @return The sequence number (big-endian uint)\n function extractSequenceWitness(bytes memory _input) internal pure returns (uint32) {\n uint32 _leSeqence = uint32(extractSequenceLEWitness(_input));\n uint32 _inputeSequence = reverseUint32(_leSeqence);\n return _inputeSequence;\n }\n\n /// @notice Extracts the outpoint from the input in a tx\n /// @dev 32-byte tx id with 4-byte index\n /// @param _input The input\n /// @return The outpoint (LE bytes of prev tx hash + LE bytes of prev tx index)\n function extractOutpoint(bytes memory _input) internal pure returns (bytes memory) {\n return _input.slice(0, 36);\n }\n\n /// @notice Extracts the outpoint tx id from an input\n /// @dev 32-byte tx id\n /// @param _input The input\n /// @return The tx id (little-endian bytes)\n function extractInputTxIdLE(bytes memory _input) internal pure returns (bytes32) {\n return _input.slice32(0);\n }\n\n /// @notice Extracts the outpoint tx id from an input\n /// starting at the specified position\n /// @dev 32-byte tx id\n /// @param _input The byte array containing the input\n /// @param _at The position of the input\n /// @return The tx id (little-endian bytes)\n function extractInputTxIdLeAt(bytes memory _input, uint256 _at) internal pure returns (bytes32) {\n return _input.slice32(_at);\n }\n\n /// @notice Extracts the LE tx input index from the input in a tx\n /// @dev 4-byte tx index\n /// @param _input The input\n /// @return The tx index (little-endian bytes)\n function extractTxIndexLE(bytes memory _input) internal pure returns (bytes4) {\n return _input.slice4(32);\n }\n\n /// @notice Extracts the LE tx input index from the input in a tx\n /// starting at the specified position\n /// @dev 4-byte tx index\n /// @param _input The byte array containing the input\n /// @param _at The position of the input\n /// @return The tx index (little-endian bytes)\n function extractTxIndexLeAt(bytes memory _input, uint256 _at) internal pure returns (bytes4) {\n return _input.slice4(32 + _at);\n }\n\n /* ****** */\n /* Output */\n /* ****** */\n\n /// @notice Determines the length of an output\n /// @dev Works with any properly formatted output\n /// @param _output The output\n /// @return The length indicated by the prefix, error if invalid length\n function determineOutputLength(bytes memory _output) internal pure returns (uint256) {\n return determineOutputLengthAt(_output, 0);\n }\n\n /// @notice Determines the length of an output\n /// starting at the specified position\n /// @dev Works with any properly formatted output\n /// @param _output The byte array containing the output\n /// @param _at The position of the output\n /// @return The length indicated by the prefix, error if invalid length\n function determineOutputLengthAt(bytes memory _output, uint256 _at) internal pure returns (uint256) {\n if (_output.length < 9 + _at) {\n return ERR_BAD_ARG;\n }\n uint256 _varIntDataLen;\n uint256 _scriptPubkeyLength;\n (_varIntDataLen, _scriptPubkeyLength) = parseVarIntAt(_output, 8 + _at);\n\n if (_varIntDataLen == ERR_BAD_ARG) {\n return ERR_BAD_ARG;\n }\n\n // 8-byte value, 1-byte for tag itself\n return 8 + 1 + _varIntDataLen + _scriptPubkeyLength;\n }\n\n /// @notice Extracts the output at a given index in the TxOuts vector\n /// @dev Iterates over the vout. If you need to extract multiple, write a custom function\n /// @param _vout The _vout to extract from\n /// @param _index The 0-indexed location of the output to extract\n /// @return The specified output\n function extractOutputAtIndex(bytes memory _vout, uint256 _index) internal pure returns (bytes memory) {\n uint256 _varIntDataLen;\n uint256 _nOuts;\n\n (_varIntDataLen, _nOuts) = parseVarInt(_vout);\n require(_varIntDataLen != ERR_BAD_ARG, \"Read overrun during VarInt parsing\");\n require(_index < _nOuts, \"Vout read overrun\");\n\n uint256 _len = 0;\n uint256 _offset = 1 + _varIntDataLen;\n\n for (uint256 _i = 0; _i < _index; _i ++) {\n _len = determineOutputLengthAt(_vout, _offset);\n require(_len != ERR_BAD_ARG, \"Bad VarInt in scriptPubkey\");\n _offset += _len;\n }\n\n _len = determineOutputLengthAt(_vout, _offset);\n require(_len != ERR_BAD_ARG, \"Bad VarInt in scriptPubkey\");\n return _vout.slice(_offset, _len);\n }\n\n /// @notice Extracts the value bytes from the output in a tx\n /// @dev Value is an 8-byte little-endian number\n /// @param _output The output\n /// @return The output value as LE bytes\n function extractValueLE(bytes memory _output) internal pure returns (bytes8) {\n return _output.slice8(0);\n }\n\n /// @notice Extracts the value from the output in a tx\n /// @dev Value is an 8-byte little-endian number\n /// @param _output The output\n /// @return The output value\n function extractValue(bytes memory _output) internal pure returns (uint64) {\n uint64 _leValue = uint64(extractValueLE(_output));\n uint64 _beValue = reverseUint64(_leValue);\n return _beValue;\n }\n\n /// @notice Extracts the value from the output in a tx\n /// @dev Value is an 8-byte little-endian number\n /// @param _output The byte array containing the output\n /// @param _at The starting index of the output in the array\n /// @return The output value\n function extractValueAt(bytes memory _output, uint256 _at) internal pure returns (uint64) {\n uint64 _leValue = uint64(_output.slice8(_at));\n uint64 _beValue = reverseUint64(_leValue);\n return _beValue;\n }\n\n /// @notice Extracts the data from an op return output\n /// @dev Returns hex\"\" if no data or not an op return\n /// @param _output The output\n /// @return Any data contained in the opreturn output, null if not an op return\n function extractOpReturnData(bytes memory _output) internal pure returns (bytes memory) {\n if (_output[9] != hex\"6a\") {\n return hex\"\";\n }\n bytes1 _dataLen = _output[10];\n return _output.slice(11, uint256(uint8(_dataLen)));\n }\n\n /// @notice Extracts the hash from the output script\n /// @dev Determines type by the length prefix and validates format\n /// @param _output The output\n /// @return The hash committed to by the pk_script, or null for errors\n function extractHash(bytes memory _output) internal pure returns (bytes memory) {\n return extractHashAt(_output, 8, _output.length - 8);\n }\n\n /// @notice Extracts the hash from the output script\n /// @dev Determines type by the length prefix and validates format\n /// @param _output The byte array containing the output\n /// @param _at The starting index of the output script in the array\n /// (output start + 8)\n /// @param _len The length of the output script\n /// (output length - 8)\n /// @return The hash committed to by the pk_script, or null for errors\n function extractHashAt(\n bytes memory _output,\n uint256 _at,\n uint256 _len\n ) internal pure returns (bytes memory) {\n uint8 _scriptLen = uint8(_output[_at]);\n\n // don't have to worry about overflow here.\n // if _scriptLen + 1 overflows, then output length would have to be < 1\n // for this check to pass. if it's < 1, then we errored when assigning\n // _scriptLen\n if (_scriptLen + 1 != _len) {\n return hex\"\";\n }\n\n if (uint8(_output[_at + 1]) == 0) {\n if (_scriptLen < 2) {\n return hex\"\";\n }\n uint256 _payloadLen = uint8(_output[_at + 2]);\n // Check for maliciously formatted witness outputs.\n // No need to worry about underflow as long b/c of the `< 2` check\n if (_payloadLen != _scriptLen - 2 || (_payloadLen != 0x20 && _payloadLen != 0x14)) {\n return hex\"\";\n }\n return _output.slice(_at + 3, _payloadLen);\n } else {\n bytes3 _tag = _output.slice3(_at);\n // p2pkh\n if (_tag == hex\"1976a9\") {\n // Check for maliciously formatted p2pkh\n // No need to worry about underflow, b/c of _scriptLen check\n if (uint8(_output[_at + 3]) != 0x14 ||\n _output.slice2(_at + _len - 2) != hex\"88ac\") {\n return hex\"\";\n }\n return _output.slice(_at + 4, 20);\n //p2sh\n } else if (_tag == hex\"17a914\") {\n // Check for maliciously formatted p2sh\n // No need to worry about underflow, b/c of _scriptLen check\n if (uint8(_output[_at + _len - 1]) != 0x87) {\n return hex\"\";\n }\n return _output.slice(_at + 3, 20);\n }\n }\n return hex\"\"; /* NB: will trigger on OPRETURN and any non-standard that doesn't overrun */\n }\n\n /* ********** */\n /* Witness TX */\n /* ********** */\n\n\n /// @notice Checks that the vin passed up is properly formatted\n /// @dev Consider a vin with a valid vout in its scriptsig\n /// @param _vin Raw bytes length-prefixed input vector\n /// @return True if it represents a validly formatted vin\n function validateVin(bytes memory _vin) internal pure returns (bool) {\n uint256 _varIntDataLen;\n uint256 _nIns;\n\n (_varIntDataLen, _nIns) = parseVarInt(_vin);\n\n // Not valid if it says there are too many or no inputs\n if (_nIns == 0 || _varIntDataLen == ERR_BAD_ARG) {\n return false;\n }\n\n uint256 _offset = 1 + _varIntDataLen;\n\n for (uint256 i = 0; i < _nIns; i++) {\n // If we're at the end, but still expect more\n if (_offset >= _vin.length) {\n return false;\n }\n\n // Grab the next input and determine its length.\n uint256 _nextLen = determineInputLengthAt(_vin, _offset);\n if (_nextLen == ERR_BAD_ARG) {\n return false;\n }\n\n // Increase the offset by that much\n _offset += _nextLen;\n }\n\n // Returns false if we're not exactly at the end\n return _offset == _vin.length;\n }\n\n /// @notice Checks that the vout passed up is properly formatted\n /// @dev Consider a vout with a valid scriptpubkey\n /// @param _vout Raw bytes length-prefixed output vector\n /// @return True if it represents a validly formatted vout\n function validateVout(bytes memory _vout) internal pure returns (bool) {\n uint256 _varIntDataLen;\n uint256 _nOuts;\n\n (_varIntDataLen, _nOuts) = parseVarInt(_vout);\n\n // Not valid if it says there are too many or no outputs\n if (_nOuts == 0 || _varIntDataLen == ERR_BAD_ARG) {\n return false;\n }\n\n uint256 _offset = 1 + _varIntDataLen;\n\n for (uint256 i = 0; i < _nOuts; i++) {\n // If we're at the end, but still expect more\n if (_offset >= _vout.length) {\n return false;\n }\n\n // Grab the next output and determine its length.\n // Increase the offset by that much\n uint256 _nextLen = determineOutputLengthAt(_vout, _offset);\n if (_nextLen == ERR_BAD_ARG) {\n return false;\n }\n\n _offset += _nextLen;\n }\n\n // Returns false if we're not exactly at the end\n return _offset == _vout.length;\n }\n\n\n\n /* ************ */\n /* Block Header */\n /* ************ */\n\n /// @notice Extracts the transaction merkle root from a block header\n /// @dev Use verifyHash256Merkle to verify proofs with this root\n /// @param _header The header\n /// @return The merkle root (little-endian)\n function extractMerkleRootLE(bytes memory _header) internal pure returns (bytes32) {\n return _header.slice32(36);\n }\n\n /// @notice Extracts the target from a block header\n /// @dev Target is a 256-bit number encoded as a 3-byte mantissa and 1-byte exponent\n /// @param _header The header\n /// @return The target threshold\n function extractTarget(bytes memory _header) internal pure returns (uint256) {\n return extractTargetAt(_header, 0);\n }\n\n /// @notice Extracts the target from a block header\n /// @dev Target is a 256-bit number encoded as a 3-byte mantissa and 1-byte exponent\n /// @param _header The array containing the header\n /// @param at The start of the header\n /// @return The target threshold\n function extractTargetAt(bytes memory _header, uint256 at) internal pure returns (uint256) {\n uint24 _m = uint24(_header.slice3(72 + at));\n uint8 _e = uint8(_header[75 + at]);\n uint256 _mantissa = uint256(reverseUint24(_m));\n uint _exponent = _e - 3;\n\n return _mantissa * (256 ** _exponent);\n }\n\n /// @notice Calculate difficulty from the difficulty 1 target and current target\n /// @dev Difficulty 1 is 0x1d00ffff on mainnet and testnet\n /// @dev Difficulty 1 is a 256-bit number encoded as a 3-byte mantissa and 1-byte exponent\n /// @param _target The current target\n /// @return The block difficulty (bdiff)\n function calculateDifficulty(uint256 _target) internal pure returns (uint256) {\n // Difficulty 1 calculated from 0x1d00ffff\n return DIFF1_TARGET.div(_target);\n }\n\n /// @notice Extracts the previous block's hash from a block header\n /// @dev Block headers do NOT include block number :(\n /// @param _header The header\n /// @return The previous block's hash (little-endian)\n function extractPrevBlockLE(bytes memory _header) internal pure returns (bytes32) {\n return _header.slice32(4);\n }\n\n /// @notice Extracts the previous block's hash from a block header\n /// @dev Block headers do NOT include block number :(\n /// @param _header The array containing the header\n /// @param at The start of the header\n /// @return The previous block's hash (little-endian)\n function extractPrevBlockLEAt(\n bytes memory _header,\n uint256 at\n ) internal pure returns (bytes32) {\n return _header.slice32(4 + at);\n }\n\n /// @notice Extracts the timestamp from a block header\n /// @dev Time is not 100% reliable\n /// @param _header The header\n /// @return The timestamp (little-endian bytes)\n function extractTimestampLE(bytes memory _header) internal pure returns (bytes4) {\n return _header.slice4(68);\n }\n\n /// @notice Extracts the timestamp from a block header\n /// @dev Time is not 100% reliable\n /// @param _header The header\n /// @return The timestamp (uint)\n function extractTimestamp(bytes memory _header) internal pure returns (uint32) {\n return reverseUint32(uint32(extractTimestampLE(_header)));\n }\n\n /// @notice Extracts the expected difficulty from a block header\n /// @dev Does NOT verify the work\n /// @param _header The header\n /// @return The difficulty as an integer\n function extractDifficulty(bytes memory _header) internal pure returns (uint256) {\n return calculateDifficulty(extractTarget(_header));\n }\n\n /// @notice Concatenates and hashes two inputs for merkle proving\n /// @param _a The first hash\n /// @param _b The second hash\n /// @return The double-sha256 of the concatenated hashes\n function _hash256MerkleStep(bytes memory _a, bytes memory _b) internal view returns (bytes32) {\n return hash256View(abi.encodePacked(_a, _b));\n }\n\n /// @notice Concatenates and hashes two inputs for merkle proving\n /// @param _a The first hash\n /// @param _b The second hash\n /// @return The double-sha256 of the concatenated hashes\n function _hash256MerkleStep(bytes32 _a, bytes32 _b) internal view returns (bytes32) {\n return hash256Pair(_a, _b);\n }\n\n\n /// @notice Verifies a Bitcoin-style merkle tree\n /// @dev Leaves are 0-indexed. Inefficient version.\n /// @param _proof The proof. Tightly packed LE sha256 hashes. The last hash is the root\n /// @param _index The index of the leaf\n /// @return true if the proof is valid, else false\n function verifyHash256Merkle(bytes memory _proof, uint _index) internal view returns (bool) {\n // Not an even number of hashes\n if (_proof.length % 32 != 0) {\n return false;\n }\n\n // Special case for coinbase-only blocks\n if (_proof.length == 32) {\n return true;\n }\n\n // Should never occur\n if (_proof.length == 64) {\n return false;\n }\n\n bytes32 _root = _proof.slice32(_proof.length - 32);\n bytes32 _current = _proof.slice32(0);\n bytes memory _tree = _proof.slice(32, _proof.length - 64);\n\n return verifyHash256Merkle(_current, _tree, _root, _index);\n }\n\n /// @notice Verifies a Bitcoin-style merkle tree\n /// @dev Leaves are 0-indexed. Efficient version.\n /// @param _leaf The leaf of the proof. LE sha256 hash.\n /// @param _tree The intermediate nodes in the proof.\n /// Tightly packed LE sha256 hashes.\n /// @param _root The root of the proof. LE sha256 hash.\n /// @param _index The index of the leaf\n /// @return true if the proof is valid, else false\n function verifyHash256Merkle(\n bytes32 _leaf,\n bytes memory _tree,\n bytes32 _root,\n uint _index\n ) internal view returns (bool) {\n // Not an even number of hashes\n if (_tree.length % 32 != 0) {\n return false;\n }\n\n // Should never occur\n if (_tree.length == 0) {\n return false;\n }\n\n uint _idx = _index;\n bytes32 _current = _leaf;\n\n // i moves in increments of 32\n for (uint i = 0; i < _tree.length; i += 32) {\n if (_idx % 2 == 1) {\n _current = _hash256MerkleStep(_tree.slice32(i), _current);\n } else {\n _current = _hash256MerkleStep(_current, _tree.slice32(i));\n }\n _idx = _idx >> 1;\n }\n return _current == _root;\n }\n\n /*\n NB: https://github.com/bitcoin/bitcoin/blob/78dae8caccd82cfbfd76557f1fb7d7557c7b5edb/src/pow.cpp#L49-L72\n NB: We get a full-bitlength target from this. For comparison with\n header-encoded targets we need to mask it with the header target\n e.g. (full & truncated) == truncated\n */\n /// @notice performs the bitcoin difficulty retarget\n /// @dev implements the Bitcoin algorithm precisely\n /// @param _previousTarget the target of the previous period\n /// @param _firstTimestamp the timestamp of the first block in the difficulty period\n /// @param _secondTimestamp the timestamp of the last block in the difficulty period\n /// @return the new period's target threshold\n function retargetAlgorithm(\n uint256 _previousTarget,\n uint256 _firstTimestamp,\n uint256 _secondTimestamp\n ) internal pure returns (uint256) {\n uint256 _elapsedTime = _secondTimestamp.sub(_firstTimestamp);\n\n // Normalize ratio to factor of 4 if very long or very short\n if (_elapsedTime < RETARGET_PERIOD.div(4)) {\n _elapsedTime = RETARGET_PERIOD.div(4);\n }\n if (_elapsedTime > RETARGET_PERIOD.mul(4)) {\n _elapsedTime = RETARGET_PERIOD.mul(4);\n }\n\n /*\n NB: high targets e.g. ffff0020 can cause overflows here\n so we divide it by 256**2, then multiply by 256**2 later\n we know the target is evenly divisible by 256**2, so this isn't an issue\n */\n\n uint256 _adjusted = _previousTarget.div(65536).mul(_elapsedTime);\n return _adjusted.div(RETARGET_PERIOD).mul(65536);\n }\n}\n" + }, + "@keep-network/bitcoin-spv-sol/contracts/BytesLib.sol": { + "content": "pragma solidity ^0.8.4;\n\n/*\n\nhttps://github.com/GNSPS/solidity-bytes-utils/\n\nThis is free and unencumbered software released into the public domain.\n\nAnyone is free to copy, modify, publish, use, compile, sell, or\ndistribute this software, either in source code form or as a compiled\nbinary, for any purpose, commercial or non-commercial, and by any\nmeans.\n\nIn jurisdictions that recognize copyright laws, the author or authors\nof this software dedicate any and all copyright interest in the\nsoftware to the public domain. We make this dedication for the benefit\nof the public at large and to the detriment of our heirs and\nsuccessors. We intend this dedication to be an overt act of\nrelinquishment in perpetuity of all present and future rights to this\nsoftware under copyright law.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND,\nEXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF\nMERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.\nIN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR\nOTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,\nARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR\nOTHER DEALINGS IN THE SOFTWARE.\n\nFor more information, please refer to \n*/\n\n\n/** @title BytesLib **/\n/** @author https://github.com/GNSPS **/\n\nlibrary BytesLib {\n function concat(bytes memory _preBytes, bytes memory _postBytes) internal pure returns (bytes memory) {\n bytes memory tempBytes;\n\n assembly {\n // Get a location of some free memory and store it in tempBytes as\n // Solidity does for memory variables.\n tempBytes := mload(0x40)\n\n // Store the length of the first bytes array at the beginning of\n // the memory for tempBytes.\n let length := mload(_preBytes)\n mstore(tempBytes, length)\n\n // Maintain a memory counter for the current write location in the\n // temp bytes array by adding the 32 bytes for the array length to\n // the starting location.\n let mc := add(tempBytes, 0x20)\n // Stop copying when the memory counter reaches the length of the\n // first bytes array.\n let end := add(mc, length)\n\n for {\n // Initialize a copy counter to the start of the _preBytes data,\n // 32 bytes into its memory.\n let cc := add(_preBytes, 0x20)\n } lt(mc, end) {\n // Increase both counters by 32 bytes each iteration.\n mc := add(mc, 0x20)\n cc := add(cc, 0x20)\n } {\n // Write the _preBytes data into the tempBytes memory 32 bytes\n // at a time.\n mstore(mc, mload(cc))\n }\n\n // Add the length of _postBytes to the current length of tempBytes\n // and store it as the new length in the first 32 bytes of the\n // tempBytes memory.\n length := mload(_postBytes)\n mstore(tempBytes, add(length, mload(tempBytes)))\n\n // Move the memory counter back from a multiple of 0x20 to the\n // actual end of the _preBytes data.\n mc := end\n // Stop copying when the memory counter reaches the new combined\n // length of the arrays.\n end := add(mc, length)\n\n for {\n let cc := add(_postBytes, 0x20)\n } lt(mc, end) {\n mc := add(mc, 0x20)\n cc := add(cc, 0x20)\n } {\n mstore(mc, mload(cc))\n }\n\n // Update the free-memory pointer by padding our last write location\n // to 32 bytes: add 31 bytes to the end of tempBytes to move to the\n // next 32 byte block, then round down to the nearest multiple of\n // 32. If the sum of the length of the two arrays is zero then add\n // one before rounding down to leave a blank 32 bytes (the length block with 0).\n mstore(0x40, and(\n add(add(end, iszero(add(length, mload(_preBytes)))), 31),\n not(31) // Round down to the nearest 32 bytes.\n ))\n }\n\n return tempBytes;\n }\n\n function concatStorage(bytes storage _preBytes, bytes memory _postBytes) internal {\n assembly {\n // Read the first 32 bytes of _preBytes storage, which is the length\n // of the array. (We don't need to use the offset into the slot\n // because arrays use the entire slot.)\n let fslot := sload(_preBytes.slot)\n // Arrays of 31 bytes or less have an even value in their slot,\n // while longer arrays have an odd value. The actual length is\n // the slot divided by two for odd values, and the lowest order\n // byte divided by two for even values.\n // If the slot is even, bitwise and the slot with 255 and divide by\n // two to get the length. If the slot is odd, bitwise and the slot\n // with -1 and divide by two.\n let slength := div(and(fslot, sub(mul(0x100, iszero(and(fslot, 1))), 1)), 2)\n let mlength := mload(_postBytes)\n let newlength := add(slength, mlength)\n // slength can contain both the length and contents of the array\n // if length < 32 bytes so let's prepare for that\n // v. http://solidity.readthedocs.io/en/latest/miscellaneous.html#layout-of-state-variables-in-storage\n switch add(lt(slength, 32), lt(newlength, 32))\n case 2 {\n // Since the new array still fits in the slot, we just need to\n // update the contents of the slot.\n // uint256(bytes_storage) = uint256(bytes_storage) + uint256(bytes_memory) + new_length\n sstore(\n _preBytes.slot,\n // all the modifications to the slot are inside this\n // next block\n add(\n // we can just add to the slot contents because the\n // bytes we want to change are the LSBs\n fslot,\n add(\n mul(\n div(\n // load the bytes from memory\n mload(add(_postBytes, 0x20)),\n // zero all bytes to the right\n exp(0x100, sub(32, mlength))\n ),\n // and now shift left the number of bytes to\n // leave space for the length in the slot\n exp(0x100, sub(32, newlength))\n ),\n // increase length by the double of the memory\n // bytes length\n mul(mlength, 2)\n )\n )\n )\n }\n case 1 {\n // The stored value fits in the slot, but the combined value\n // will exceed it.\n // get the keccak hash to get the contents of the array\n mstore(0x0, _preBytes.slot)\n let sc := add(keccak256(0x0, 0x20), div(slength, 32))\n\n // save new length\n sstore(_preBytes.slot, add(mul(newlength, 2), 1))\n\n // The contents of the _postBytes array start 32 bytes into\n // the structure. Our first read should obtain the `submod`\n // bytes that can fit into the unused space in the last word\n // of the stored array. To get this, we read 32 bytes starting\n // from `submod`, so the data we read overlaps with the array\n // contents by `submod` bytes. Masking the lowest-order\n // `submod` bytes allows us to add that value directly to the\n // stored value.\n\n let submod := sub(32, slength)\n let mc := add(_postBytes, submod)\n let end := add(_postBytes, mlength)\n let mask := sub(exp(0x100, submod), 1)\n\n sstore(\n sc,\n add(\n and(\n fslot,\n 0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff00\n ),\n and(mload(mc), mask)\n )\n )\n\n for {\n mc := add(mc, 0x20)\n sc := add(sc, 1)\n } lt(mc, end) {\n sc := add(sc, 1)\n mc := add(mc, 0x20)\n } {\n sstore(sc, mload(mc))\n }\n\n mask := exp(0x100, sub(mc, end))\n\n sstore(sc, mul(div(mload(mc), mask), mask))\n }\n default {\n // get the keccak hash to get the contents of the array\n mstore(0x0, _preBytes.slot)\n // Start copying to the last used word of the stored array.\n let sc := add(keccak256(0x0, 0x20), div(slength, 32))\n\n // save new length\n sstore(_preBytes.slot, add(mul(newlength, 2), 1))\n\n // Copy over the first `submod` bytes of the new data as in\n // case 1 above.\n let slengthmod := mod(slength, 32)\n let mlengthmod := mod(mlength, 32)\n let submod := sub(32, slengthmod)\n let mc := add(_postBytes, submod)\n let end := add(_postBytes, mlength)\n let mask := sub(exp(0x100, submod), 1)\n\n sstore(sc, add(sload(sc), and(mload(mc), mask)))\n\n for {\n sc := add(sc, 1)\n mc := add(mc, 0x20)\n } lt(mc, end) {\n sc := add(sc, 1)\n mc := add(mc, 0x20)\n } {\n sstore(sc, mload(mc))\n }\n\n mask := exp(0x100, sub(mc, end))\n\n sstore(sc, mul(div(mload(mc), mask), mask))\n }\n }\n }\n\n function slice(bytes memory _bytes, uint _start, uint _length) internal pure returns (bytes memory res) {\n if (_length == 0) {\n return hex\"\";\n }\n uint _end = _start + _length;\n require(_end > _start && _bytes.length >= _end, \"Slice out of bounds\");\n\n assembly {\n // Alloc bytes array with additional 32 bytes afterspace and assign it's size\n res := mload(0x40)\n mstore(0x40, add(add(res, 64), _length))\n mstore(res, _length)\n\n // Compute distance between source and destination pointers\n let diff := sub(res, add(_bytes, _start))\n\n for {\n let src := add(add(_bytes, 32), _start)\n let end := add(src, _length)\n } lt(src, end) {\n src := add(src, 32)\n } {\n mstore(add(src, diff), mload(src))\n }\n }\n }\n\n /// @notice Take a slice of the byte array, overwriting the destination.\n /// The length of the slice will equal the length of the destination array.\n /// @dev Make sure the destination array has afterspace if required.\n /// @param _bytes The source array\n /// @param _dest The destination array.\n /// @param _start The location to start in the source array.\n function sliceInPlace(\n bytes memory _bytes,\n bytes memory _dest,\n uint _start\n ) internal pure {\n uint _length = _dest.length;\n uint _end = _start + _length;\n require(_end > _start && _bytes.length >= _end, \"Slice out of bounds\");\n\n assembly {\n for {\n let src := add(add(_bytes, 32), _start)\n let res := add(_dest, 32)\n let end := add(src, _length)\n } lt(src, end) {\n src := add(src, 32)\n res := add(res, 32)\n } {\n mstore(res, mload(src))\n }\n }\n }\n\n // Static slice functions, no bounds checking\n /// @notice take a 32-byte slice from the specified position\n function slice32(bytes memory _bytes, uint _start) internal pure returns (bytes32 res) {\n assembly {\n res := mload(add(add(_bytes, 32), _start))\n }\n }\n\n /// @notice take a 20-byte slice from the specified position\n function slice20(bytes memory _bytes, uint _start) internal pure returns (bytes20) {\n return bytes20(slice32(_bytes, _start));\n }\n\n /// @notice take a 8-byte slice from the specified position\n function slice8(bytes memory _bytes, uint _start) internal pure returns (bytes8) {\n return bytes8(slice32(_bytes, _start));\n }\n\n /// @notice take a 4-byte slice from the specified position\n function slice4(bytes memory _bytes, uint _start) internal pure returns (bytes4) {\n return bytes4(slice32(_bytes, _start));\n }\n\n /// @notice take a 3-byte slice from the specified position\n function slice3(bytes memory _bytes, uint _start) internal pure returns (bytes3) {\n return bytes3(slice32(_bytes, _start));\n }\n\n /// @notice take a 2-byte slice from the specified position\n function slice2(bytes memory _bytes, uint _start) internal pure returns (bytes2) {\n return bytes2(slice32(_bytes, _start));\n }\n\n function toAddress(bytes memory _bytes, uint _start) internal pure returns (address) {\n uint _totalLen = _start + 20;\n require(_totalLen > _start && _bytes.length >= _totalLen, \"Address conversion out of bounds.\");\n address tempAddress;\n\n assembly {\n tempAddress := div(mload(add(add(_bytes, 0x20), _start)), 0x1000000000000000000000000)\n }\n\n return tempAddress;\n }\n\n function toUint(bytes memory _bytes, uint _start) internal pure returns (uint256) {\n uint _totalLen = _start + 32;\n require(_totalLen > _start && _bytes.length >= _totalLen, \"Uint conversion out of bounds.\");\n uint256 tempUint;\n\n assembly {\n tempUint := mload(add(add(_bytes, 0x20), _start))\n }\n\n return tempUint;\n }\n\n function equal(bytes memory _preBytes, bytes memory _postBytes) internal pure returns (bool) {\n bool success = true;\n\n assembly {\n let length := mload(_preBytes)\n\n // if lengths don't match the arrays are not equal\n switch eq(length, mload(_postBytes))\n case 1 {\n // cb is a circuit breaker in the for loop since there's\n // no said feature for inline assembly loops\n // cb = 1 - don't breaker\n // cb = 0 - break\n let cb := 1\n\n let mc := add(_preBytes, 0x20)\n let end := add(mc, length)\n\n for {\n let cc := add(_postBytes, 0x20)\n // the next line is the loop condition:\n // while(uint(mc < end) + cb == 2)\n } eq(add(lt(mc, end), cb), 2) {\n mc := add(mc, 0x20)\n cc := add(cc, 0x20)\n } {\n // if any of these checks fails then arrays are not equal\n if iszero(eq(mload(mc), mload(cc))) {\n // unsuccess:\n success := 0\n cb := 0\n }\n }\n }\n default {\n // unsuccess:\n success := 0\n }\n }\n\n return success;\n }\n\n function equalStorage(bytes storage _preBytes, bytes memory _postBytes) internal view returns (bool) {\n bool success = true;\n\n assembly {\n // we know _preBytes_offset is 0\n let fslot := sload(_preBytes.slot)\n // Decode the length of the stored array like in concatStorage().\n let slength := div(and(fslot, sub(mul(0x100, iszero(and(fslot, 1))), 1)), 2)\n let mlength := mload(_postBytes)\n\n // if lengths don't match the arrays are not equal\n switch eq(slength, mlength)\n case 1 {\n // slength can contain both the length and contents of the array\n // if length < 32 bytes so let's prepare for that\n // v. http://solidity.readthedocs.io/en/latest/miscellaneous.html#layout-of-state-variables-in-storage\n if iszero(iszero(slength)) {\n switch lt(slength, 32)\n case 1 {\n // blank the last byte which is the length\n fslot := mul(div(fslot, 0x100), 0x100)\n\n if iszero(eq(fslot, mload(add(_postBytes, 0x20)))) {\n // unsuccess:\n success := 0\n }\n }\n default {\n // cb is a circuit breaker in the for loop since there's\n // no said feature for inline assembly loops\n // cb = 1 - don't breaker\n // cb = 0 - break\n let cb := 1\n\n // get the keccak hash to get the contents of the array\n mstore(0x0, _preBytes.slot)\n let sc := keccak256(0x0, 0x20)\n\n let mc := add(_postBytes, 0x20)\n let end := add(mc, mlength)\n\n // the next line is the loop condition:\n // while(uint(mc < end) + cb == 2)\n for {} eq(add(lt(mc, end), cb), 2) {\n sc := add(sc, 1)\n mc := add(mc, 0x20)\n } {\n if iszero(eq(sload(sc), mload(mc))) {\n // unsuccess:\n success := 0\n cb := 0\n }\n }\n }\n }\n }\n default {\n // unsuccess:\n success := 0\n }\n }\n\n return success;\n }\n\n function toBytes32(bytes memory _source) pure internal returns (bytes32 result) {\n if (_source.length == 0) {\n return 0x0;\n }\n\n assembly {\n result := mload(add(_source, 32))\n }\n }\n\n function keccak256Slice(bytes memory _bytes, uint _start, uint _length) pure internal returns (bytes32 result) {\n uint _end = _start + _length;\n require(_end > _start && _bytes.length >= _end, \"Slice out of bounds\");\n\n assembly {\n result := keccak256(add(add(_bytes, 32), _start), _length)\n }\n }\n}\n" + }, + "@keep-network/bitcoin-spv-sol/contracts/CheckBitcoinSigs.sol": { + "content": "pragma solidity ^0.8.4;\n\n/** @title CheckBitcoinSigs */\n/** @author Summa (https://summa.one) */\n\nimport {BytesLib} from \"./BytesLib.sol\";\nimport {BTCUtils} from \"./BTCUtils.sol\";\n\n\nlibrary CheckBitcoinSigs {\n\n using BytesLib for bytes;\n using BTCUtils for bytes;\n\n /// @notice Derives an Ethereum Account address from a pubkey\n /// @dev The address is the last 20 bytes of the keccak256 of the address\n /// @param _pubkey The public key X & Y. Unprefixed, as a 64-byte array\n /// @return The account address\n function accountFromPubkey(bytes memory _pubkey) internal pure returns (address) {\n require(_pubkey.length == 64, \"Pubkey must be 64-byte raw, uncompressed key.\");\n\n // keccak hash of uncompressed unprefixed pubkey\n bytes32 _digest = keccak256(_pubkey);\n return address(uint160(uint256(_digest)));\n }\n\n /// @notice Calculates the p2wpkh output script of a pubkey\n /// @dev Compresses keys to 33 bytes as required by Bitcoin\n /// @param _pubkey The public key, compressed or uncompressed\n /// @return The p2wkph output script\n function p2wpkhFromPubkey(bytes memory _pubkey) internal view returns (bytes memory) {\n bytes memory _compressedPubkey;\n uint8 _prefix;\n\n if (_pubkey.length == 64) {\n _prefix = uint8(_pubkey[_pubkey.length - 1]) % 2 == 1 ? 3 : 2;\n _compressedPubkey = abi.encodePacked(_prefix, _pubkey.slice32(0));\n } else if (_pubkey.length == 65) {\n _prefix = uint8(_pubkey[_pubkey.length - 1]) % 2 == 1 ? 3 : 2;\n _compressedPubkey = abi.encodePacked(_prefix, _pubkey.slice32(1));\n } else {\n _compressedPubkey = _pubkey;\n }\n\n require(_compressedPubkey.length == 33, \"Witness PKH requires compressed keys\");\n\n bytes20 _pubkeyHash = _compressedPubkey.hash160View();\n return abi.encodePacked(hex\"0014\", _pubkeyHash);\n }\n\n /// @notice checks a signed message's validity under a pubkey\n /// @dev does this using ecrecover because Ethereum has no soul\n /// @param _pubkey the public key to check (64 bytes)\n /// @param _digest the message digest signed\n /// @param _v the signature recovery value\n /// @param _r the signature r value\n /// @param _s the signature s value\n /// @return true if signature is valid, else false\n function checkSig(\n bytes memory _pubkey,\n bytes32 _digest,\n uint8 _v,\n bytes32 _r,\n bytes32 _s\n ) internal pure returns (bool) {\n require(_pubkey.length == 64, \"Requires uncompressed unprefixed pubkey\");\n address _expected = accountFromPubkey(_pubkey);\n address _actual = ecrecover(_digest, _v, _r, _s);\n return _actual == _expected;\n }\n\n /// @notice checks a signed message against a bitcoin p2wpkh output script\n /// @dev does this my verifying the p2wpkh matches an ethereum account\n /// @param _p2wpkhOutputScript the bitcoin output script\n /// @param _pubkey the uncompressed, unprefixed public key to check\n /// @param _digest the message digest signed\n /// @param _v the signature recovery value\n /// @param _r the signature r value\n /// @param _s the signature s value\n /// @return true if signature is valid, else false\n function checkBitcoinSig(\n bytes memory _p2wpkhOutputScript,\n bytes memory _pubkey,\n bytes32 _digest,\n uint8 _v,\n bytes32 _r,\n bytes32 _s\n ) internal view returns (bool) {\n require(_pubkey.length == 64, \"Requires uncompressed unprefixed pubkey\");\n\n bool _isExpectedSigner = keccak256(p2wpkhFromPubkey(_pubkey)) == keccak256(_p2wpkhOutputScript); // is it the expected signer?\n if (!_isExpectedSigner) {return false;}\n\n bool _sigResult = checkSig(_pubkey, _digest, _v, _r, _s);\n return _sigResult;\n }\n\n /// @notice checks if a message is the sha256 preimage of a digest\n /// @dev this is NOT the hash256! this step is necessary for ECDSA security!\n /// @param _digest the digest\n /// @param _candidate the purported preimage\n /// @return true if the preimage matches the digest, else false\n function isSha256Preimage(\n bytes memory _candidate,\n bytes32 _digest\n ) internal pure returns (bool) {\n return sha256(_candidate) == _digest;\n }\n\n /// @notice checks if a message is the keccak256 preimage of a digest\n /// @dev this step is necessary for ECDSA security!\n /// @param _digest the digest\n /// @param _candidate the purported preimage\n /// @return true if the preimage matches the digest, else false\n function isKeccak256Preimage(\n bytes memory _candidate,\n bytes32 _digest\n ) internal pure returns (bool) {\n return keccak256(_candidate) == _digest;\n }\n\n /// @notice calculates the signature hash of a Bitcoin transaction with the provided details\n /// @dev documented in bip143. many values are hardcoded here\n /// @param _outpoint the bitcoin UTXO id (32-byte txid + 4-byte output index)\n /// @param _inputPKH the input pubkeyhash (hash160(sender_pubkey))\n /// @param _inputValue the value of the input in satoshi\n /// @param _outputValue the value of the output in satoshi\n /// @param _outputScript the length-prefixed output script\n /// @return the double-sha256 (hash256) signature hash as defined by bip143\n function wpkhSpendSighash(\n bytes memory _outpoint, // 36-byte UTXO id\n bytes20 _inputPKH, // 20-byte hash160\n bytes8 _inputValue, // 8-byte LE\n bytes8 _outputValue, // 8-byte LE\n bytes memory _outputScript // lenght-prefixed output script\n ) internal view returns (bytes32) {\n // Fixes elements to easily make a 1-in 1-out sighash digest\n // Does not support timelocks\n // bytes memory _scriptCode = abi.encodePacked(\n // hex\"1976a914\", // length, dup, hash160, pkh_length\n // _inputPKH,\n // hex\"88ac\"); // equal, checksig\n\n bytes32 _hashOutputs = abi.encodePacked(\n _outputValue, // 8-byte LE\n _outputScript).hash256View();\n\n bytes memory _sighashPreimage = abi.encodePacked(\n hex\"01000000\", // version\n _outpoint.hash256View(), // hashPrevouts\n hex\"8cb9012517c817fead650287d61bdd9c68803b6bf9c64133dcab3e65b5a50cb9\", // hashSequence(00000000)\n _outpoint, // outpoint\n // p2wpkh script code\n hex\"1976a914\", // length, dup, hash160, pkh_length\n _inputPKH,\n hex\"88ac\", // equal, checksig\n // end script code\n _inputValue, // value of the input in 8-byte LE\n hex\"00000000\", // input nSequence\n _hashOutputs, // hash of the single output\n hex\"00000000\", // nLockTime\n hex\"01000000\" // SIGHASH_ALL\n );\n return _sighashPreimage.hash256View();\n }\n\n /// @notice calculates the signature hash of a Bitcoin transaction with the provided details\n /// @dev documented in bip143. many values are hardcoded here\n /// @param _outpoint the bitcoin UTXO id (32-byte txid + 4-byte output index)\n /// @param _inputPKH the input pubkeyhash (hash160(sender_pubkey))\n /// @param _inputValue the value of the input in satoshi\n /// @param _outputValue the value of the output in satoshi\n /// @param _outputPKH the output pubkeyhash (hash160(recipient_pubkey))\n /// @return the double-sha256 (hash256) signature hash as defined by bip143\n function wpkhToWpkhSighash(\n bytes memory _outpoint, // 36-byte UTXO id\n bytes20 _inputPKH, // 20-byte hash160\n bytes8 _inputValue, // 8-byte LE\n bytes8 _outputValue, // 8-byte LE\n bytes20 _outputPKH // 20-byte hash160\n ) internal view returns (bytes32) {\n return wpkhSpendSighash(\n _outpoint,\n _inputPKH,\n _inputValue,\n _outputValue,\n abi.encodePacked(\n hex\"160014\", // wpkh tag\n _outputPKH)\n );\n }\n\n /// @notice Preserved for API compatibility with older version\n /// @dev documented in bip143. many values are hardcoded here\n /// @param _outpoint the bitcoin UTXO id (32-byte txid + 4-byte output index)\n /// @param _inputPKH the input pubkeyhash (hash160(sender_pubkey))\n /// @param _inputValue the value of the input in satoshi\n /// @param _outputValue the value of the output in satoshi\n /// @param _outputPKH the output pubkeyhash (hash160(recipient_pubkey))\n /// @return the double-sha256 (hash256) signature hash as defined by bip143\n function oneInputOneOutputSighash(\n bytes memory _outpoint, // 36-byte UTXO id\n bytes20 _inputPKH, // 20-byte hash160\n bytes8 _inputValue, // 8-byte LE\n bytes8 _outputValue, // 8-byte LE\n bytes20 _outputPKH // 20-byte hash160\n ) internal view returns (bytes32) {\n return wpkhToWpkhSighash(_outpoint, _inputPKH, _inputValue, _outputValue, _outputPKH);\n }\n\n}\n" + }, + "@keep-network/bitcoin-spv-sol/contracts/SafeMath.sol": { + "content": "pragma solidity ^0.8.4;\n\n/*\nThe MIT License (MIT)\n\nCopyright (c) 2016 Smart Contract Solutions, Inc.\n\nPermission is hereby granted, free of charge, to any person obtaining\na copy of this software and associated documentation files (the\n\"Software\"), to deal in the Software without restriction, including\nwithout limitation the rights to use, copy, modify, merge, publish,\ndistribute, sublicense, and/or sell copies of the Software, and to\npermit persons to whom the Software is furnished to do so, subject to\nthe following conditions:\n\nThe above copyright notice and this permission notice shall be included\nin all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS\nOR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF\nMERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.\nIN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY\nCLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,\nTORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE\nSOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n*/\n\n\n/**\n * @title SafeMath\n * @dev Math operations with safety checks that throw on error\n */\nlibrary SafeMath {\n\n /**\n * @dev Multiplies two numbers, throws on overflow.\n */\n function mul(uint256 _a, uint256 _b) internal pure returns (uint256 c) {\n // Gas optimization: this is cheaper than asserting 'a' not being zero, but the\n // benefit is lost if 'b' is also tested.\n // See: https://github.com/OpenZeppelin/openzeppelin-solidity/pull/522\n if (_a == 0) {\n return 0;\n }\n\n c = _a * _b;\n require(c / _a == _b, \"Overflow during multiplication.\");\n return c;\n }\n\n /**\n * @dev Integer division of two numbers, truncating the quotient.\n */\n function div(uint256 _a, uint256 _b) internal pure returns (uint256) {\n // assert(_b > 0); // Solidity automatically throws when dividing by 0\n // uint256 c = _a / _b;\n // assert(_a == _b * c + _a % _b); // There is no case in which this doesn't hold\n return _a / _b;\n }\n\n /**\n * @dev Subtracts two numbers, throws on overflow (i.e. if subtrahend is greater than minuend).\n */\n function sub(uint256 _a, uint256 _b) internal pure returns (uint256) {\n require(_b <= _a, \"Underflow during subtraction.\");\n return _a - _b;\n }\n\n /**\n * @dev Adds two numbers, throws on overflow.\n */\n function add(uint256 _a, uint256 _b) internal pure returns (uint256 c) {\n c = _a + _b;\n require(c >= _a, \"Overflow during addition.\");\n return c;\n }\n}\n" + }, + "@keep-network/bitcoin-spv-sol/contracts/ValidateSPV.sol": { + "content": "pragma solidity ^0.8.4;\n\n/** @title ValidateSPV*/\n/** @author Summa (https://summa.one) */\n\nimport {BytesLib} from \"./BytesLib.sol\";\nimport {SafeMath} from \"./SafeMath.sol\";\nimport {BTCUtils} from \"./BTCUtils.sol\";\n\n\nlibrary ValidateSPV {\n\n using BTCUtils for bytes;\n using BTCUtils for uint256;\n using BytesLib for bytes;\n using SafeMath for uint256;\n\n enum InputTypes { NONE, LEGACY, COMPATIBILITY, WITNESS }\n enum OutputTypes { NONE, WPKH, WSH, OP_RETURN, PKH, SH, NONSTANDARD }\n\n uint256 constant ERR_BAD_LENGTH = 0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff;\n uint256 constant ERR_INVALID_CHAIN = 0xfffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffe;\n uint256 constant ERR_LOW_WORK = 0xfffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffd;\n\n function getErrBadLength() internal pure returns (uint256) {\n return ERR_BAD_LENGTH;\n }\n\n function getErrInvalidChain() internal pure returns (uint256) {\n return ERR_INVALID_CHAIN;\n }\n\n function getErrLowWork() internal pure returns (uint256) {\n return ERR_LOW_WORK;\n }\n\n /// @notice Validates a tx inclusion in the block\n /// @dev `index` is not a reliable indicator of location within a block\n /// @param _txid The txid (LE)\n /// @param _merkleRoot The merkle root (as in the block header)\n /// @param _intermediateNodes The proof's intermediate nodes (digests between leaf and root)\n /// @param _index The leaf's index in the tree (0-indexed)\n /// @return true if fully valid, false otherwise\n function prove(\n bytes32 _txid,\n bytes32 _merkleRoot,\n bytes memory _intermediateNodes,\n uint _index\n ) internal view returns (bool) {\n // Shortcut the empty-block case\n if (_txid == _merkleRoot && _index == 0 && _intermediateNodes.length == 0) {\n return true;\n }\n\n // If the Merkle proof failed, bubble up error\n return BTCUtils.verifyHash256Merkle(\n _txid,\n _intermediateNodes,\n _merkleRoot,\n _index\n );\n }\n\n /// @notice Hashes transaction to get txid\n /// @dev Supports Legacy and Witness\n /// @param _version 4-bytes version\n /// @param _vin Raw bytes length-prefixed input vector\n /// @param _vout Raw bytes length-prefixed output vector\n /// @param _locktime 4-byte tx locktime\n /// @return 32-byte transaction id, little endian\n function calculateTxId(\n bytes4 _version,\n bytes memory _vin,\n bytes memory _vout,\n bytes4 _locktime\n ) internal view returns (bytes32) {\n // Get transaction hash double-Sha256(version + nIns + inputs + nOuts + outputs + locktime)\n return abi.encodePacked(_version, _vin, _vout, _locktime).hash256View();\n }\n\n /// @notice Checks validity of header chain\n /// @notice Compares the hash of each header to the prevHash in the next header\n /// @param headers Raw byte array of header chain\n /// @return totalDifficulty The total accumulated difficulty of the header chain, or an error code\n function validateHeaderChain(\n bytes memory headers\n ) internal view returns (uint256 totalDifficulty) {\n\n // Check header chain length\n if (headers.length % 80 != 0) {return ERR_BAD_LENGTH;}\n\n // Initialize header start index\n bytes32 digest;\n\n totalDifficulty = 0;\n\n for (uint256 start = 0; start < headers.length; start += 80) {\n\n // After the first header, check that headers are in a chain\n if (start != 0) {\n if (!validateHeaderPrevHash(headers, start, digest)) {return ERR_INVALID_CHAIN;}\n }\n\n // ith header target\n uint256 target = headers.extractTargetAt(start);\n\n // Require that the header has sufficient work\n digest = headers.hash256Slice(start, 80);\n if(uint256(digest).reverseUint256() > target) {\n return ERR_LOW_WORK;\n }\n\n // Add ith header difficulty to difficulty sum\n totalDifficulty = totalDifficulty + target.calculateDifficulty();\n }\n }\n\n /// @notice Checks validity of header work\n /// @param digest Header digest\n /// @param target The target threshold\n /// @return true if header work is valid, false otherwise\n function validateHeaderWork(\n bytes32 digest,\n uint256 target\n ) internal pure returns (bool) {\n if (digest == bytes32(0)) {return false;}\n return (uint256(digest).reverseUint256() < target);\n }\n\n /// @notice Checks validity of header chain\n /// @dev Compares current header prevHash to previous header's digest\n /// @param headers The raw bytes array containing the header\n /// @param at The position of the header\n /// @param prevHeaderDigest The previous header's digest\n /// @return true if the connect is valid, false otherwise\n function validateHeaderPrevHash(\n bytes memory headers,\n uint256 at,\n bytes32 prevHeaderDigest\n ) internal pure returns (bool) {\n\n // Extract prevHash of current header\n bytes32 prevHash = headers.extractPrevBlockLEAt(at);\n\n // Compare prevHash of current header to previous header's digest\n if (prevHash != prevHeaderDigest) {return false;}\n\n return true;\n }\n}\n" + }, + "@keep-network/ecdsa/contracts/api/IWalletOwner.sol": { + "content": "// SPDX-License-Identifier: GPL-3.0-only\n//\n// ▓▓▌ ▓▓ ▐▓▓ ▓▓▓▓▓▓▓▓▓▓▌▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▄\n// ▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▌▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓\n// ▓▓▓▓▓▓ ▓▓▓▓▓▓▓▀ ▐▓▓▓▓▓▓ ▐▓▓▓▓▓ ▓▓▓▓▓▓ ▓▓▓▓▓ ▐▓▓▓▓▓▌ ▐▓▓▓▓▓▓\n// ▓▓▓▓▓▓▄▄▓▓▓▓▓▓▓▀ ▐▓▓▓▓▓▓▄▄▄▄ ▓▓▓▓▓▓▄▄▄▄ ▐▓▓▓▓▓▌ ▐▓▓▓▓▓▓\n// ▓▓▓▓▓▓▓▓▓▓▓▓▓▀ ▐▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓\n// ▓▓▓▓▓▓▀▀▓▓▓▓▓▓▄ ▐▓▓▓▓▓▓▀▀▀▀ ▓▓▓▓▓▓▀▀▀▀ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▀\n// ▓▓▓▓▓▓ ▀▓▓▓▓▓▓▄ ▐▓▓▓▓▓▓ ▓▓▓▓▓ ▓▓▓▓▓▓ ▓▓▓▓▓ ▐▓▓▓▓▓▌\n// ▓▓▓▓▓▓▓▓▓▓ █▓▓▓▓▓▓▓▓▓ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓\n// ▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓\n//\n// Trust math, not hardware.\n\npragma solidity 0.8.17;\n\ninterface IWalletOwner {\n /// @notice Callback function executed once a new wallet is created.\n /// @dev Should be callable only by the Wallet Registry.\n /// @param walletID Wallet's unique identifier.\n /// @param publicKeyY Wallet's public key's X coordinate.\n /// @param publicKeyY Wallet's public key's Y coordinate.\n function __ecdsaWalletCreatedCallback(\n bytes32 walletID,\n bytes32 publicKeyX,\n bytes32 publicKeyY\n ) external;\n\n /// @notice Callback function executed once a wallet heartbeat failure\n /// is detected.\n /// @dev Should be callable only by the Wallet Registry.\n /// @param walletID Wallet's unique identifier.\n /// @param publicKeyY Wallet's public key's X coordinate.\n /// @param publicKeyY Wallet's public key's Y coordinate.\n function __ecdsaWalletHeartbeatFailedCallback(\n bytes32 walletID,\n bytes32 publicKeyX,\n bytes32 publicKeyY\n ) external;\n}\n" + }, + "@keep-network/ecdsa/contracts/api/IWalletRegistry.sol": { + "content": "// SPDX-License-Identifier: GPL-3.0-only\n//\n// ▓▓▌ ▓▓ ▐▓▓ ▓▓▓▓▓▓▓▓▓▓▌▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▄\n// ▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▌▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓\n// ▓▓▓▓▓▓ ▓▓▓▓▓▓▓▀ ▐▓▓▓▓▓▓ ▐▓▓▓▓▓ ▓▓▓▓▓▓ ▓▓▓▓▓ ▐▓▓▓▓▓▌ ▐▓▓▓▓▓▓\n// ▓▓▓▓▓▓▄▄▓▓▓▓▓▓▓▀ ▐▓▓▓▓▓▓▄▄▄▄ ▓▓▓▓▓▓▄▄▄▄ ▐▓▓▓▓▓▌ ▐▓▓▓▓▓▓\n// ▓▓▓▓▓▓▓▓▓▓▓▓▓▀ ▐▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓\n// ▓▓▓▓▓▓▀▀▓▓▓▓▓▓▄ ▐▓▓▓▓▓▓▀▀▀▀ ▓▓▓▓▓▓▀▀▀▀ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▀\n// ▓▓▓▓▓▓ ▀▓▓▓▓▓▓▄ ▐▓▓▓▓▓▓ ▓▓▓▓▓ ▓▓▓▓▓▓ ▓▓▓▓▓ ▐▓▓▓▓▓▌\n// ▓▓▓▓▓▓▓▓▓▓ █▓▓▓▓▓▓▓▓▓ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓\n// ▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓\n//\n// Trust math, not hardware.\n\npragma solidity 0.8.17;\n\nimport \"../libraries/EcdsaDkg.sol\";\n\ninterface IWalletRegistry {\n /// @notice Requests a new wallet creation.\n /// @dev Only the Wallet Owner can call this function.\n function requestNewWallet() external;\n\n /// @notice Closes an existing wallet.\n /// @param walletID ID of the wallet.\n /// @dev Only the Wallet Owner can call this function.\n function closeWallet(bytes32 walletID) external;\n\n /// @notice Adds all signing group members of the wallet with the given ID\n /// to the slashing queue of the staking contract. The notifier will\n /// receive reward per each group member from the staking contract\n /// notifiers treasury. The reward is scaled by the\n /// `rewardMultiplier` provided as a parameter.\n /// @param amount Amount of tokens to seize from each signing group member\n /// @param rewardMultiplier Fraction of the staking contract notifiers\n /// reward the notifier should receive; should be between [0, 100]\n /// @param notifier Address of the misbehavior notifier\n /// @param walletID ID of the wallet\n /// @param walletMembersIDs Identifiers of the wallet signing group members\n /// @dev Only the Wallet Owner can call this function.\n /// Requirements:\n /// - The expression `keccak256(abi.encode(walletMembersIDs))` must\n /// be exactly the same as the hash stored under `membersIdsHash`\n /// for the given `walletID`. Those IDs are not directly stored\n /// in the contract for gas efficiency purposes but they can be\n /// read from appropriate `DkgResultSubmitted` and `DkgResultApproved`\n /// events.\n /// - `rewardMultiplier` must be between [0, 100].\n /// - This function does revert if staking contract call reverts.\n /// The calling code needs to handle the potential revert.\n function seize(\n uint96 amount,\n uint256 rewardMultiplier,\n address notifier,\n bytes32 walletID,\n uint32[] calldata walletMembersIDs\n ) external;\n\n /// @notice Gets public key of a wallet with a given wallet ID.\n /// The public key is returned in an uncompressed format as a 64-byte\n /// concatenation of X and Y coordinates.\n /// @param walletID ID of the wallet.\n /// @return Uncompressed public key of the wallet.\n function getWalletPublicKey(bytes32 walletID)\n external\n view\n returns (bytes memory);\n\n /// @notice Check current wallet creation state.\n function getWalletCreationState() external view returns (EcdsaDkg.State);\n\n /// @notice Checks whether the given operator is a member of the given\n /// wallet signing group.\n /// @param walletID ID of the wallet\n /// @param walletMembersIDs Identifiers of the wallet signing group members\n /// @param operator Address of the checked operator\n /// @param walletMemberIndex Position of the operator in the wallet signing\n /// group members list\n /// @return True - if the operator is a member of the given wallet signing\n /// group. False - otherwise.\n /// @dev Requirements:\n /// - The `operator` parameter must be an actual sortition pool operator.\n /// - The expression `keccak256(abi.encode(walletMembersIDs))` must\n /// be exactly the same as the hash stored under `membersIdsHash`\n /// for the given `walletID`. Those IDs are not directly stored\n /// in the contract for gas efficiency purposes but they can be\n /// read from appropriate `DkgResultSubmitted` and `DkgResultApproved`\n /// events.\n /// - The `walletMemberIndex` must be in range [1, walletMembersIDs.length]\n function isWalletMember(\n bytes32 walletID,\n uint32[] calldata walletMembersIDs,\n address operator,\n uint256 walletMemberIndex\n ) external view returns (bool);\n}\n" + }, + "@keep-network/ecdsa/contracts/EcdsaDkgValidator.sol": { + "content": "// SPDX-License-Identifier: GPL-3.0-only\n//\n// ▓▓▌ ▓▓ ▐▓▓ ▓▓▓▓▓▓▓▓▓▓▌▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▄\n// ▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▌▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓\n// ▓▓▓▓▓▓ ▓▓▓▓▓▓▓▀ ▐▓▓▓▓▓▓ ▐▓▓▓▓▓ ▓▓▓▓▓▓ ▓▓▓▓▓ ▐▓▓▓▓▓▌ ▐▓▓▓▓▓▓\n// ▓▓▓▓▓▓▄▄▓▓▓▓▓▓▓▀ ▐▓▓▓▓▓▓▄▄▄▄ ▓▓▓▓▓▓▄▄▄▄ ▐▓▓▓▓▓▌ ▐▓▓▓▓▓▓\n// ▓▓▓▓▓▓▓▓▓▓▓▓▓▀ ▐▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓\n// ▓▓▓▓▓▓▀▀▓▓▓▓▓▓▄ ▐▓▓▓▓▓▓▀▀▀▀ ▓▓▓▓▓▓▀▀▀▀ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▀\n// ▓▓▓▓▓▓ ▀▓▓▓▓▓▓▄ ▐▓▓▓▓▓▓ ▓▓▓▓▓ ▓▓▓▓▓▓ ▓▓▓▓▓ ▐▓▓▓▓▓▌\n// ▓▓▓▓▓▓▓▓▓▓ █▓▓▓▓▓▓▓▓▓ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓\n// ▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓\n//\n// Trust math, not hardware.\n\n// Initial version copied from Keep Network Random Beacon:\n// https://github.com/keep-network/keep-core/blob/5138c7628868dbeed3ae2164f76fccc6c1fbb9e8/solidity/random-beacon/contracts/DKGValidator.sol\n//\n// With the following differences:\n// - group public key length,\n// - group size and related thresholds,\n// - documentation.\n\npragma solidity 0.8.17;\n\nimport \"@openzeppelin/contracts/utils/cryptography/ECDSA.sol\";\nimport \"@keep-network/random-beacon/contracts/libraries/BytesLib.sol\";\nimport \"@keep-network/sortition-pools/contracts/SortitionPool.sol\";\nimport \"./libraries/EcdsaDkg.sol\";\n\n/// @title DKG result validator\n/// @notice EcdsaDkgValidator allows performing a full validation of DKG result,\n/// including checking the format of fields in the result, declared\n/// selected group members, and signatures of operators supporting the\n/// result. The operator submitting the result should perform the\n/// validation using a free contract call before submitting the result\n/// to ensure their result is valid and can not be challenged. All other\n/// network operators should perform validation of the submitted result\n/// using a free contract call and challenge the result if the\n/// validation fails.\ncontract EcdsaDkgValidator {\n using BytesLib for bytes;\n using ECDSA for bytes32;\n\n /// @dev Size of a group in DKG.\n uint256 public constant groupSize = 100;\n\n /// @dev The minimum number of group members needed to interact according to\n /// the protocol to produce a signature. The adversary can not learn\n /// anything about the key as long as it does not break into\n /// groupThreshold+1 of members.\n uint256 public constant groupThreshold = 51;\n\n /// @dev The minimum number of active and properly behaving group members\n /// during the DKG needed to accept the result. This number is higher\n /// than `groupThreshold` to keep a safety margin for members becoming\n /// inactive after DKG so that the group can still produce signature.\n uint256 public constant activeThreshold = 90; // 90% of groupSize\n\n /// @dev Size in bytes of a public key produced by group members during the\n /// the DKG. The length assumes uncompressed ECDSA public key.\n uint256 public constant publicKeyByteSize = 64;\n\n /// @dev Size in bytes of a single signature produced by operator supporting\n /// DKG result.\n uint256 public constant signatureByteSize = 65;\n\n SortitionPool public immutable sortitionPool;\n\n constructor(SortitionPool _sortitionPool) {\n sortitionPool = _sortitionPool;\n }\n\n /// @notice Performs a full validation of DKG result, including checking the\n /// format of fields in the result, declared selected group members,\n /// and signatures of operators supporting the result.\n /// @param seed seed used to start the DKG and select group members\n /// @param startBlock DKG start block\n /// @return isValid true if the result is valid, false otherwise\n /// @return errorMsg validation error message; empty for a valid result\n function validate(\n EcdsaDkg.Result calldata result,\n uint256 seed,\n uint256 startBlock\n ) external view returns (bool isValid, string memory errorMsg) {\n (bool hasValidFields, string memory error) = validateFields(result);\n if (!hasValidFields) {\n return (false, error);\n }\n\n if (!validateSignatures(result, startBlock)) {\n return (false, \"Invalid signatures\");\n }\n\n if (!validateGroupMembers(result, seed)) {\n return (false, \"Invalid group members\");\n }\n\n // At this point all group members and misbehaved members were verified\n if (!validateMembersHash(result)) {\n return (false, \"Invalid members hash\");\n }\n\n return (true, \"\");\n }\n\n /// @notice Performs a static validation of DKG result fields: lengths,\n /// ranges, and order of arrays.\n /// @return isValid true if the result is valid, false otherwise\n /// @return errorMsg validation error message; empty for a valid result\n function validateFields(EcdsaDkg.Result calldata result)\n public\n pure\n returns (bool isValid, string memory errorMsg)\n {\n if (result.groupPubKey.length != publicKeyByteSize) {\n return (false, \"Malformed group public key\");\n }\n\n // The number of misbehaved members can not exceed the threshold.\n // Misbehaved member indices needs to be unique, between [1, groupSize],\n // and sorted in ascending order.\n uint8[] calldata misbehavedMembersIndices = result\n .misbehavedMembersIndices;\n if (groupSize - misbehavedMembersIndices.length < activeThreshold) {\n return (false, \"Too many members misbehaving during DKG\");\n }\n if (misbehavedMembersIndices.length > 1) {\n if (\n misbehavedMembersIndices[0] < 1 ||\n misbehavedMembersIndices[misbehavedMembersIndices.length - 1] >\n groupSize\n ) {\n return (false, \"Corrupted misbehaved members indices\");\n }\n for (uint256 i = 1; i < misbehavedMembersIndices.length; i++) {\n if (\n misbehavedMembersIndices[i - 1] >=\n misbehavedMembersIndices[i]\n ) {\n return (false, \"Corrupted misbehaved members indices\");\n }\n }\n }\n\n // Each signature needs to have a correct length and signatures need to\n // be provided.\n uint256 signaturesCount = result.signatures.length / signatureByteSize;\n if (result.signatures.length == 0) {\n return (false, \"No signatures provided\");\n }\n if (result.signatures.length % signatureByteSize != 0) {\n return (false, \"Malformed signatures array\");\n }\n\n // We expect the same amount of signatures as the number of declared\n // group member indices that signed the result.\n uint256[] calldata signingMembersIndices = result.signingMembersIndices;\n if (signaturesCount != signingMembersIndices.length) {\n return (false, \"Unexpected signatures count\");\n }\n if (signaturesCount < groupThreshold) {\n return (false, \"Too few signatures\");\n }\n if (signaturesCount > groupSize) {\n return (false, \"Too many signatures\");\n }\n\n // Signing member indices needs to be unique, between [1,groupSize],\n // and sorted in ascending order.\n if (\n signingMembersIndices[0] < 1 ||\n signingMembersIndices[signingMembersIndices.length - 1] > groupSize\n ) {\n return (false, \"Corrupted signing member indices\");\n }\n for (uint256 i = 1; i < signingMembersIndices.length; i++) {\n if (signingMembersIndices[i - 1] >= signingMembersIndices[i]) {\n return (false, \"Corrupted signing member indices\");\n }\n }\n\n return (true, \"\");\n }\n\n /// @notice Performs validation of group members as declared in DKG\n /// result against group members selected by the sortition pool.\n /// @param seed seed used to start the DKG and select group members\n /// @return true if group members matches; false otherwise\n function validateGroupMembers(EcdsaDkg.Result calldata result, uint256 seed)\n public\n view\n returns (bool)\n {\n uint32[] calldata resultMembers = result.members;\n uint32[] memory actualGroupMembers = sortitionPool.selectGroup(\n groupSize,\n bytes32(seed)\n );\n if (resultMembers.length != actualGroupMembers.length) {\n return false;\n }\n for (uint256 i = 0; i < resultMembers.length; i++) {\n if (resultMembers[i] != actualGroupMembers[i]) {\n return false;\n }\n }\n return true;\n }\n\n /// @notice Performs validation of signatures supplied in DKG result.\n /// Note that this function does not check if addresses which\n /// supplied signatures supporting the result are the ones selected\n /// to the group by sortition pool. This function should be used\n /// together with `validateGroupMembers`.\n /// @param startBlock DKG start block\n /// @return true if group members matches; false otherwise\n function validateSignatures(\n EcdsaDkg.Result calldata result,\n uint256 startBlock\n ) public view returns (bool) {\n bytes32 hash = keccak256(\n abi.encode(\n block.chainid,\n result.groupPubKey,\n result.misbehavedMembersIndices,\n startBlock\n )\n ).toEthSignedMessageHash();\n\n uint256[] calldata signingMembersIndices = result.signingMembersIndices;\n uint32[] memory signingMemberIds = new uint32[](\n signingMembersIndices.length\n );\n for (uint256 i = 0; i < signingMembersIndices.length; i++) {\n signingMemberIds[i] = result.members[signingMembersIndices[i] - 1];\n }\n\n address[] memory signingMemberAddresses = sortitionPool.getIDOperators(\n signingMemberIds\n );\n\n bytes memory current; // Current signature to be checked.\n\n uint256 signaturesCount = result.signatures.length / signatureByteSize;\n for (uint256 i = 0; i < signaturesCount; i++) {\n current = result.signatures.slice(\n signatureByteSize * i,\n signatureByteSize\n );\n address recoveredAddress = hash.recover(current);\n\n if (signingMemberAddresses[i] != recoveredAddress) {\n return false;\n }\n }\n\n return true;\n }\n\n /// @notice Performs validation of hashed group members that actively took\n /// part in DKG.\n /// @param result DKG result\n /// @return true if calculated result's group members hash matches with the\n /// one that is challenged.\n function validateMembersHash(EcdsaDkg.Result calldata result)\n public\n pure\n returns (bool)\n {\n if (result.misbehavedMembersIndices.length > 0) {\n // members that generated a group signing key\n uint32[] memory groupMembers = new uint32[](\n result.members.length - result.misbehavedMembersIndices.length\n );\n uint256 k = 0; // misbehaved members counter\n uint256 j = 0; // group members counter\n for (uint256 i = 0; i < result.members.length; i++) {\n // misbehaved member indices start from 1, so we need to -1 on misbehaved\n if (i != result.misbehavedMembersIndices[k] - 1) {\n groupMembers[j] = result.members[i];\n j++;\n } else if (k < result.misbehavedMembersIndices.length - 1) {\n k++;\n }\n }\n\n return keccak256(abi.encode(groupMembers)) == result.membersHash;\n }\n\n return keccak256(abi.encode(result.members)) == result.membersHash;\n }\n}\n" + }, + "@keep-network/ecdsa/contracts/libraries/EcdsaAuthorization.sol": { + "content": "// SPDX-License-Identifier: GPL-3.0-only\n//\n// ▓▓▌ ▓▓ ▐▓▓ ▓▓▓▓▓▓▓▓▓▓▌▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▄\n// ▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▌▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓\n// ▓▓▓▓▓▓ ▓▓▓▓▓▓▓▀ ▐▓▓▓▓▓▓ ▐▓▓▓▓▓ ▓▓▓▓▓▓ ▓▓▓▓▓ ▐▓▓▓▓▓▌ ▐▓▓▓▓▓▓\n// ▓▓▓▓▓▓▄▄▓▓▓▓▓▓▓▀ ▐▓▓▓▓▓▓▄▄▄▄ ▓▓▓▓▓▓▄▄▄▄ ▐▓▓▓▓▓▌ ▐▓▓▓▓▓▓\n// ▓▓▓▓▓▓▓▓▓▓▓▓▓▀ ▐▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓\n// ▓▓▓▓▓▓▀▀▓▓▓▓▓▓▄ ▐▓▓▓▓▓▓▀▀▀▀ ▓▓▓▓▓▓▀▀▀▀ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▀\n// ▓▓▓▓▓▓ ▀▓▓▓▓▓▓▄ ▐▓▓▓▓▓▓ ▓▓▓▓▓ ▓▓▓▓▓▓ ▓▓▓▓▓ ▐▓▓▓▓▓▌\n// ▓▓▓▓▓▓▓▓▓▓ █▓▓▓▓▓▓▓▓▓ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓\n// ▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓\n//\n//\n\npragma solidity 0.8.17;\n\nimport \"@keep-network/sortition-pools/contracts/SortitionPool.sol\";\nimport \"@threshold-network/solidity-contracts/contracts/staking/IStaking.sol\";\n\n/// @notice Library managing the state of stake authorizations for ECDSA\n/// operator contract and the presence of operators in the sortition\n/// pool based on the stake authorized for them.\nlibrary EcdsaAuthorization {\n struct Parameters {\n // The minimum authorization required by ECDSA application so that\n // operator can join the sortition pool and do the work.\n uint96 minimumAuthorization;\n // Authorization decrease delay in seconds between the time\n // authorization decrease is requested and the time the authorization\n // decrease can be approved. It is always the same value, no matter if\n // authorization decrease amount is small, significant, or if it is\n // a decrease to zero.\n uint64 authorizationDecreaseDelay;\n // The time period before the authorization decrease delay end,\n // during which the authorization decrease request can be overwritten.\n //\n // When the request is overwritten, the authorization decrease delay is\n // reset.\n //\n // For example, if `authorizationDecraseChangePeriod` is set to 4\n // days, `authorizationDecreaseDelay` is set to 14 days, and someone\n // requested authorization decrease, it means they can not\n // request another decrease for the first 10 days. After 10 days pass,\n // they can request again and overwrite the previous authorization\n // decrease request. The delay time will reset for them and they\n // will have to wait another 10 days to alter it and 14 days to\n // approve it.\n //\n // This value protects against malicious operators who manipulate\n // their weight by overwriting authorization decrease request, and\n // lowering or increasing their eligible stake this way.\n //\n // If set to a value equal to `authorizationDecreaseDelay, it means\n // that authorization decrease request can be always overwritten.\n // If set to zero, it means authorization decrease request can not be\n // overwritten until the delay end, and one needs to wait for the entire\n // authorization decrease delay to approve their decrease and request\n // for another one or to overwrite the pending one.\n //\n // (1) authorization decrease requested timestamp\n // (2) from this moment authorization decrease request can be\n // overwritten\n // (3) from this moment authorization decrease request can be\n // approved, assuming it was NOT overwritten in (2)\n //\n // (1) (2) (3)\n // --x------------------------------x--------------------------x---->\n // | \\________________________/\n // | authorizationDecreaseChangePeriod\n // \\______________________________________________________/\n // authorizationDecreaseDelay\n //\n uint64 authorizationDecreaseChangePeriod;\n // This struct doesn't contain `__gap` property as the structure is\n // stored inside `Data` struct, that already have a gap that can be used\n // on upgrade.\n }\n\n struct AuthorizationDecrease {\n uint96 decreasingBy; // amount\n uint64 decreasingAt; // timestamp\n }\n\n struct Data {\n Parameters parameters;\n mapping(address => address) stakingProviderToOperator;\n mapping(address => address) operatorToStakingProvider;\n mapping(address => AuthorizationDecrease) pendingDecreases;\n // Reserved storage space in case we need to add more variables.\n // See https://docs.openzeppelin.com/contracts/4.x/upgradeable#storage_gaps\n // slither-disable-next-line unused-state\n uint256[46] __gap;\n }\n\n event OperatorRegistered(\n address indexed stakingProvider,\n address indexed operator\n );\n\n event AuthorizationIncreased(\n address indexed stakingProvider,\n address indexed operator,\n uint96 fromAmount,\n uint96 toAmount\n );\n\n event AuthorizationDecreaseRequested(\n address indexed stakingProvider,\n address indexed operator,\n uint96 fromAmount,\n uint96 toAmount,\n uint64 decreasingAt\n );\n\n event AuthorizationDecreaseApproved(address indexed stakingProvider);\n\n event InvoluntaryAuthorizationDecreaseFailed(\n address indexed stakingProvider,\n address indexed operator,\n uint96 fromAmount,\n uint96 toAmount\n );\n\n event OperatorJoinedSortitionPool(\n address indexed stakingProvider,\n address indexed operator\n );\n\n event OperatorStatusUpdated(\n address indexed stakingProvider,\n address indexed operator\n );\n\n /// @notice Sets the minimum authorization for ECDSA application. Without\n /// at least the minimum authorization, staking provider is not\n /// eligible to join and operate in the network.\n function setMinimumAuthorization(\n Data storage self,\n uint96 _minimumAuthorization\n ) internal {\n self.parameters.minimumAuthorization = _minimumAuthorization;\n }\n\n /// @notice Sets the authorization decrease delay. It is the time in seconds\n /// that needs to pass between the time authorization decrease is\n /// requested and the time the authorization decrease can be\n /// approved, no matter the authorization decrease amount.\n function setAuthorizationDecreaseDelay(\n Data storage self,\n uint64 _authorizationDecreaseDelay\n ) internal {\n self\n .parameters\n .authorizationDecreaseDelay = _authorizationDecreaseDelay;\n }\n\n /// @notice Sets the authorization decrease change period. It is the time\n /// period before the authorization decrease delay end,\n /// during which the authorization decrease request can be\n /// overwritten.\n function setAuthorizationDecreaseChangePeriod(\n Data storage self,\n uint64 _authorizationDecreaseChangePeriod\n ) internal {\n self\n .parameters\n .authorizationDecreaseChangePeriod = _authorizationDecreaseChangePeriod;\n }\n\n /// @notice Used by staking provider to set operator address that will\n /// operate ECDSA node. The given staking provider can set operator\n /// address only one time. The operator address can not be changed\n /// and must be unique. Reverts if the operator is already set for\n /// the staking provider or if the operator address is already in\n /// use. Reverts if there is a pending authorization decrease for\n /// the staking provider.\n function registerOperator(Data storage self, address operator) internal {\n address stakingProvider = msg.sender;\n\n require(operator != address(0), \"Operator can not be zero address\");\n require(\n self.stakingProviderToOperator[stakingProvider] == address(0),\n \"Operator already set for the staking provider\"\n );\n require(\n self.operatorToStakingProvider[operator] == address(0),\n \"Operator address already in use\"\n );\n\n // Authorization request for a staking provider who has not yet\n // registered their operator can be approved immediately.\n // We need to make sure that the approval happens before operator\n // is registered to do not let the operator join the sortition pool\n // with an unresolved authorization decrease request that can be\n // approved at any point.\n AuthorizationDecrease storage decrease = self.pendingDecreases[\n stakingProvider\n ];\n require(\n decrease.decreasingAt == 0,\n \"There is a pending authorization decrease request\"\n );\n\n emit OperatorRegistered(stakingProvider, operator);\n\n self.stakingProviderToOperator[stakingProvider] = operator;\n self.operatorToStakingProvider[operator] = stakingProvider;\n }\n\n /// @notice Used by T staking contract to inform the application that the\n /// authorized stake amount for the given staking provider increased.\n ///\n /// Reverts if the authorization amount is below the minimum.\n ///\n /// The function is not updating the sortition pool. Sortition pool\n /// state needs to be updated by the operator with a call to\n /// `joinSortitionPool` or `updateOperatorStatus`.\n ///\n /// @dev Should only be callable by T staking contract.\n function authorizationIncreased(\n Data storage self,\n address stakingProvider,\n uint96 fromAmount,\n uint96 toAmount\n ) internal {\n require(\n toAmount >= self.parameters.minimumAuthorization,\n \"Authorization below the minimum\"\n );\n\n // Note that this function does not require the operator address to be\n // set for the given staking provider. This allows the stake owner\n // who is also an authorizer to increase the authorization before the\n // staking provider sets the operator. This allows delegating stake\n // and increasing authorization immediately one after another without\n // having to wait for the staking provider to do their part.\n\n address operator = self.stakingProviderToOperator[stakingProvider];\n emit AuthorizationIncreased(\n stakingProvider,\n operator,\n fromAmount,\n toAmount\n );\n }\n\n /// @notice Used by T staking contract to inform the application that the\n /// authorization decrease for the given staking provider has been\n /// requested.\n ///\n /// Reverts if the amount after deauthorization would be non-zero\n /// and lower than the minimum authorization.\n ///\n /// Reverts if another authorization decrease request is pending for\n /// the staking provider and not enough time passed since the\n /// original request (see `authorizationDecreaseChangePeriod`).\n ///\n /// If the operator is not known (`registerOperator` was not called)\n /// it lets to `approveAuthorizationDecrease` immediately. If the\n /// operator is known (`registerOperator` was called), the operator\n /// needs to update state of the sortition pool with a call to\n /// `joinSortitionPool` or `updateOperatorStatus`. After the\n /// sortition pool state is in sync, authorization decrease delay\n /// starts.\n ///\n /// After authorization decrease delay passes, authorization\n /// decrease request needs to be approved with a call to\n /// `approveAuthorizationDecrease` function.\n ///\n /// If there is a pending authorization decrease request, it is\n /// overwritten, but only if enough time passed since the original\n /// request. Otherwise, the function reverts.\n ///\n /// @dev Should only be callable by T staking contract.\n function authorizationDecreaseRequested(\n Data storage self,\n address stakingProvider,\n uint96 fromAmount,\n uint96 toAmount\n ) internal {\n require(\n toAmount == 0 || toAmount >= self.parameters.minimumAuthorization,\n \"Authorization amount should be 0 or above the minimum\"\n );\n\n address operator = self.stakingProviderToOperator[stakingProvider];\n\n uint64 decreasingAt;\n\n if (operator == address(0)) {\n // Operator is not known. It means `registerOperator` was not\n // called yet, and there is no chance the operator could\n // call `joinSortitionPool`. We can let to approve authorization\n // decrease immediately because that operator was never in the\n // sortition pool.\n\n // solhint-disable-next-line not-rely-on-time\n decreasingAt = uint64(block.timestamp);\n } else {\n // Operator is known. It means that this operator is or was in\n // the sortition pool. Before authorization decrease delay starts,\n // the operator needs to update the state of the sortition pool\n // with a call to `joinSortitionPool` or `updateOperatorStatus`.\n // For now, we set `decreasingAt` as \"never decreasing\" and let\n // it be updated by `joinSortitionPool` or `updateOperatorStatus`\n // once we know the sortition pool is in sync.\n decreasingAt = type(uint64).max;\n }\n\n uint96 decreasingBy = fromAmount - toAmount;\n\n AuthorizationDecrease storage decreaseRequest = self.pendingDecreases[\n stakingProvider\n ];\n\n uint64 pendingDecreaseAt = decreaseRequest.decreasingAt;\n if (pendingDecreaseAt != 0 && pendingDecreaseAt != type(uint64).max) {\n // If there is already a pending authorization decrease request for\n // this staking provider and that request has been activated\n // (sortition pool was updated), require enough time to pass before\n // it can be overwritten.\n require(\n // solhint-disable-next-line not-rely-on-time\n block.timestamp >=\n pendingDecreaseAt -\n self.parameters.authorizationDecreaseChangePeriod,\n \"Not enough time passed since the original request\"\n );\n }\n\n decreaseRequest.decreasingBy = decreasingBy;\n decreaseRequest.decreasingAt = decreasingAt;\n\n emit AuthorizationDecreaseRequested(\n stakingProvider,\n operator,\n fromAmount,\n toAmount,\n decreasingAt\n );\n }\n\n /// @notice Approves the previously registered authorization decrease\n /// request. Reverts if authorization decrease delay have not passed\n /// yet or if the authorization decrease was not requested for the\n /// given staking provider.\n function approveAuthorizationDecrease(\n Data storage self,\n IStaking tokenStaking,\n address stakingProvider\n ) internal {\n AuthorizationDecrease storage decrease = self.pendingDecreases[\n stakingProvider\n ];\n require(\n decrease.decreasingAt > 0,\n \"Authorization decrease not requested\"\n );\n require(\n decrease.decreasingAt != type(uint64).max,\n \"Authorization decrease request not activated\"\n );\n require(\n // solhint-disable-next-line not-rely-on-time\n block.timestamp >= decrease.decreasingAt,\n \"Authorization decrease delay not passed\"\n );\n\n emit AuthorizationDecreaseApproved(stakingProvider);\n\n // slither-disable-next-line unused-return\n tokenStaking.approveAuthorizationDecrease(stakingProvider);\n delete self.pendingDecreases[stakingProvider];\n }\n\n /// @notice Used by T staking contract to inform the application the\n /// authorization has been decreased for the given staking provider\n /// involuntarily, as a result of slashing.\n ///\n /// If the operator is not known (`registerOperator` was not called)\n /// the function does nothing. The operator was never in a sortition\n /// pool so there is nothing to update.\n ///\n /// If the operator is known, sortition pool is unlocked, and the\n /// operator is in the sortition pool, the sortition pool state is\n /// updated. If the sortition pool is locked, update needs to be\n /// postponed. Every other staker is incentivized to call\n /// `updateOperatorStatus` for the problematic operator to increase\n /// their own rewards in the pool.\n ///\n /// @dev Should only be callable by T staking contract.\n function involuntaryAuthorizationDecrease(\n Data storage self,\n IStaking tokenStaking,\n SortitionPool sortitionPool,\n address stakingProvider,\n uint96 fromAmount,\n uint96 toAmount\n ) internal {\n address operator = self.stakingProviderToOperator[stakingProvider];\n\n if (operator == address(0)) {\n // Operator is not known. It means `registerOperator` was not\n // called yet, and there is no chance the operator could\n // call `joinSortitionPool`. We can just ignore this update because\n // operator was never in the sortition pool.\n return;\n } else {\n // Operator is known. It means that this operator is or was in the\n // sortition pool and the sortition pool may need to be updated.\n //\n // If the sortition pool is not locked and the operator is in the\n // sortition pool, we are updating it.\n //\n // To keep stakes synchronized between applications when staking\n // providers are slashed, without the risk of running out of gas,\n // the staking contract queues up slashings and let users process\n // the transactions. When an application slashes one or more staking\n // providers, it adds them to the slashing queue on the staking\n // contract. A queue entry contains the staking provider’s address\n // and the amount they are due to be slashed.\n //\n // When there is at least one staking provider in the slashing\n // queue, any account can submit a transaction processing one or\n // more staking providers' slashings, and collecting a reward for\n // doing so. A queued slashing is processed by updating the staking\n // provider’s stake to the post-slashing amount, updating authorized\n // amount for each affected application, and notifying all affected\n // applications that the staking provider’s authorized stake has\n // been reduced due to slashing.\n //\n // The entire idea is that the process transaction is expensive\n // because each application needs to be updated, so the reward for\n // the processor is hefty and comes from the slashed tokens.\n // Practically, it means that if the sortition pool is unlocked, and\n // can be updated, it should be updated because we already paid\n // someone for updating it.\n //\n // If the sortition pool is locked, update needs to wait. Other\n // sortition pool members are incentivized to call\n // `updateOperatorStatus` for the problematic operator because they\n // will increase their rewards this way.\n if (sortitionPool.isOperatorInPool(operator)) {\n if (sortitionPool.isLocked()) {\n emit InvoluntaryAuthorizationDecreaseFailed(\n stakingProvider,\n operator,\n fromAmount,\n toAmount\n );\n } else {\n updateOperatorStatus(\n self,\n tokenStaking,\n sortitionPool,\n operator\n );\n }\n }\n }\n }\n\n /// @notice Lets the operator join the sortition pool. The operator address\n /// must be known - before calling this function, it has to be\n /// appointed by the staking provider by calling `registerOperator`.\n /// Also, the operator must have the minimum authorization required\n /// by ECDSA. Function reverts if there is no minimum stake\n /// authorized or if the operator is not known. If there was an\n /// authorization decrease requested, it is activated by starting\n /// the authorization decrease delay.\n function joinSortitionPool(\n Data storage self,\n IStaking tokenStaking,\n SortitionPool sortitionPool\n ) internal {\n address operator = msg.sender;\n\n address stakingProvider = self.operatorToStakingProvider[operator];\n require(stakingProvider != address(0), \"Unknown operator\");\n\n AuthorizationDecrease storage decrease = self.pendingDecreases[\n stakingProvider\n ];\n\n uint96 _eligibleStake = eligibleStake(\n self,\n tokenStaking,\n stakingProvider,\n decrease.decreasingBy\n );\n\n require(_eligibleStake != 0, \"Authorization below the minimum\");\n\n emit OperatorJoinedSortitionPool(stakingProvider, operator);\n\n sortitionPool.insertOperator(operator, _eligibleStake);\n\n // If there is a pending authorization decrease request, activate it.\n // At this point, the sortition pool state is up to date so the\n // authorization decrease delay can start counting.\n if (decrease.decreasingAt == type(uint64).max) {\n decrease.decreasingAt =\n // solhint-disable-next-line not-rely-on-time\n uint64(block.timestamp) +\n self.parameters.authorizationDecreaseDelay;\n }\n }\n\n /// @notice Updates status of the operator in the sortition pool. If there\n /// was an authorization decrease requested, it is activated by\n /// starting the authorization decrease delay.\n /// Function reverts if the operator is not known.\n function updateOperatorStatus(\n Data storage self,\n IStaking tokenStaking,\n SortitionPool sortitionPool,\n address operator\n ) internal {\n address stakingProvider = self.operatorToStakingProvider[operator];\n require(stakingProvider != address(0), \"Unknown operator\");\n\n AuthorizationDecrease storage decrease = self.pendingDecreases[\n stakingProvider\n ];\n\n emit OperatorStatusUpdated(stakingProvider, operator);\n\n if (sortitionPool.isOperatorInPool(operator)) {\n uint96 _eligibleStake = eligibleStake(\n self,\n tokenStaking,\n stakingProvider,\n decrease.decreasingBy\n );\n\n sortitionPool.updateOperatorStatus(operator, _eligibleStake);\n }\n\n // If there is a pending authorization decrease request, activate it.\n // At this point, the sortition pool state is up to date so the\n // authorization decrease delay can start counting.\n if (decrease.decreasingAt == type(uint64).max) {\n decrease.decreasingAt =\n // solhint-disable-next-line not-rely-on-time\n uint64(block.timestamp) +\n self.parameters.authorizationDecreaseDelay;\n }\n }\n\n /// @notice Checks if the operator's authorized stake is in sync with\n /// operator's weight in the sortition pool.\n /// If the operator is not in the sortition pool and their\n /// authorized stake is non-zero, function returns false.\n function isOperatorUpToDate(\n Data storage self,\n IStaking tokenStaking,\n SortitionPool sortitionPool,\n address operator\n ) internal view returns (bool) {\n address stakingProvider = self.operatorToStakingProvider[operator];\n require(stakingProvider != address(0), \"Unknown operator\");\n\n AuthorizationDecrease storage decrease = self.pendingDecreases[\n stakingProvider\n ];\n\n uint96 _eligibleStake = eligibleStake(\n self,\n tokenStaking,\n stakingProvider,\n decrease.decreasingBy\n );\n\n if (!sortitionPool.isOperatorInPool(operator)) {\n return _eligibleStake == 0;\n } else {\n return sortitionPool.isOperatorUpToDate(operator, _eligibleStake);\n }\n }\n\n /// @notice Returns the current value of the staking provider's eligible\n /// stake. Eligible stake is defined as the currently authorized\n /// stake minus the pending authorization decrease. Eligible stake\n /// is what is used for operator's weight in the pool. If the\n /// authorized stake minus the pending authorization decrease is\n /// below the minimum authorization, eligible stake is 0.\n /// @dev This function can be exposed to the public in contrast to the\n /// second variant accepting `decreasingBy` as a parameter.\n function eligibleStake(\n Data storage self,\n IStaking tokenStaking,\n address stakingProvider\n ) internal view returns (uint96) {\n return\n eligibleStake(\n self,\n tokenStaking,\n stakingProvider,\n pendingAuthorizationDecrease(self, stakingProvider)\n );\n }\n\n /// @notice Returns the current value of the staking provider's eligible\n /// stake. Eligible stake is defined as the currently authorized\n /// stake minus the pending authorization decrease. Eligible stake\n /// is what is used for operator's weight in the pool. If the\n /// authorized stake minus the pending authorization decrease is\n /// below the minimum authorization, eligible stake is 0.\n /// @dev This function is not intended to be exposes to the public.\n /// `decreasingBy` must be fetched from `pendingDecreases` mapping and\n /// it is passed as a parameter to optimize gas usage of functions that\n /// call `eligibleStake` and need to use `AuthorizationDecrease`\n /// fetched from `pendingDecreases` for some additional logic.\n function eligibleStake(\n Data storage self,\n IStaking tokenStaking,\n address stakingProvider,\n uint96 decreasingBy\n ) internal view returns (uint96) {\n uint96 authorizedStake = tokenStaking.authorizedStake(\n stakingProvider,\n address(this)\n );\n\n uint96 _eligibleStake = authorizedStake > decreasingBy\n ? authorizedStake - decreasingBy\n : 0;\n\n if (_eligibleStake < self.parameters.minimumAuthorization) {\n return 0;\n } else {\n return _eligibleStake;\n }\n }\n\n /// @notice Returns the amount of stake that is pending authorization\n /// decrease for the given staking provider. If no authorization\n /// decrease has been requested, returns zero.\n function pendingAuthorizationDecrease(\n Data storage self,\n address stakingProvider\n ) internal view returns (uint96) {\n AuthorizationDecrease storage decrease = self.pendingDecreases[\n stakingProvider\n ];\n\n return decrease.decreasingBy;\n }\n\n /// @notice Returns the remaining time in seconds that needs to pass before\n /// the requested authorization decrease can be approved.\n /// If the sortition pool state was not updated yet by the operator\n /// after requesting the authorization decrease, returns\n /// `type(uint64).max`.\n function remainingAuthorizationDecreaseDelay(\n Data storage self,\n address stakingProvider\n ) internal view returns (uint64) {\n AuthorizationDecrease storage decrease = self.pendingDecreases[\n stakingProvider\n ];\n\n if (decrease.decreasingAt == type(uint64).max) {\n return type(uint64).max;\n }\n\n // solhint-disable-next-line not-rely-on-time\n uint64 _now = uint64(block.timestamp);\n return _now > decrease.decreasingAt ? 0 : decrease.decreasingAt - _now;\n }\n}\n" + }, + "@keep-network/ecdsa/contracts/libraries/EcdsaDkg.sol": { + "content": "// SPDX-License-Identifier: GPL-3.0-only\n//\n// ▓▓▌ ▓▓ ▐▓▓ ▓▓▓▓▓▓▓▓▓▓▌▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▄\n// ▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▌▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓\n// ▓▓▓▓▓▓ ▓▓▓▓▓▓▓▀ ▐▓▓▓▓▓▓ ▐▓▓▓▓▓ ▓▓▓▓▓▓ ▓▓▓▓▓ ▐▓▓▓▓▓▌ ▐▓▓▓▓▓▓\n// ▓▓▓▓▓▓▄▄▓▓▓▓▓▓▓▀ ▐▓▓▓▓▓▓▄▄▄▄ ▓▓▓▓▓▓▄▄▄▄ ▐▓▓▓▓▓▌ ▐▓▓▓▓▓▓\n// ▓▓▓▓▓▓▓▓▓▓▓▓▓▀ ▐▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓\n// ▓▓▓▓▓▓▀▀▓▓▓▓▓▓▄ ▐▓▓▓▓▓▓▀▀▀▀ ▓▓▓▓▓▓▀▀▀▀ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▀\n// ▓▓▓▓▓▓ ▀▓▓▓▓▓▓▄ ▐▓▓▓▓▓▓ ▓▓▓▓▓ ▓▓▓▓▓▓ ▓▓▓▓▓ ▐▓▓▓▓▓▌\n// ▓▓▓▓▓▓▓▓▓▓ █▓▓▓▓▓▓▓▓▓ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓\n// ▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓\n//\n//\n\n// Initial version copied from Keep Network Random Beacon:\n// https://github.com/keep-network/keep-core/blob/5138c7628868dbeed3ae2164f76fccc6c1fbb9e8/solidity/random-beacon/contracts/libraries/DKG.sol\n//\n// With the following differences:\n// - the group size was set to 100,\n// - offchainDkgTimeout was removed,\n// - submission eligibility verification is not performed on-chain,\n// - submission eligibility delay was replaced with a submission timeout,\n// - seed timeout notification requires seedTimeout period to pass.\n\npragma solidity 0.8.17;\n\nimport \"@openzeppelin/contracts-upgradeable/utils/cryptography/ECDSAUpgradeable.sol\";\nimport \"@keep-network/sortition-pools/contracts/SortitionPool.sol\";\nimport \"@keep-network/random-beacon/contracts/libraries/BytesLib.sol\";\nimport \"../EcdsaDkgValidator.sol\";\n\nlibrary EcdsaDkg {\n using BytesLib for bytes;\n using ECDSAUpgradeable for bytes32;\n\n struct Parameters {\n // Time in blocks during which a seed is expected to be delivered.\n // DKG starts only after a seed is delivered. The time the contract\n // awaits for a seed is not included in the DKG timeout.\n uint256 seedTimeout;\n // Time in blocks during which a submitted result can be challenged.\n uint256 resultChallengePeriodLength;\n // Extra gas required to be left at the end of the challenge DKG result\n // transaction.\n uint256 resultChallengeExtraGas;\n // Time in blocks during which a result is expected to be submitted.\n uint256 resultSubmissionTimeout;\n // Time in blocks during which only the result submitter is allowed to\n // approve it. Once this period ends and the submitter have not approved\n // the result, anyone can do it.\n uint256 submitterPrecedencePeriodLength;\n // This struct doesn't contain `__gap` property as the structure is\n // stored inside `Data` struct, that already have a gap that can be used\n // on upgrade.\n }\n\n struct Data {\n // Address of the Sortition Pool contract.\n SortitionPool sortitionPool;\n // Address of the EcdsaDkgValidator contract.\n EcdsaDkgValidator dkgValidator;\n // DKG parameters. The parameters should persist between DKG executions.\n // They should be updated with dedicated set functions only when DKG is not\n // in progress.\n Parameters parameters;\n // Time in block at which DKG state was locked.\n uint256 stateLockBlock;\n // Time in blocks at which DKG started.\n uint256 startBlock;\n // Seed used to start DKG.\n uint256 seed;\n // Time in blocks that should be added to result submission eligibility\n // delay calculation. It is used in case of a challenge to adjust\n // DKG timeout calculation.\n uint256 resultSubmissionStartBlockOffset;\n // Hash of submitted DKG result.\n bytes32 submittedResultHash;\n // Block number from the moment of the DKG result submission.\n uint256 submittedResultBlock;\n // Reserved storage space in case we need to add more variables.\n // See https://docs.openzeppelin.com/contracts/4.x/upgradeable#storage_gaps\n // slither-disable-next-line unused-state\n uint256[38] __gap;\n }\n\n /// @notice DKG result.\n struct Result {\n // Claimed submitter candidate group member index.\n // Must be in range [1, groupSize].\n uint256 submitterMemberIndex;\n // Generated candidate group public key\n bytes groupPubKey;\n // Array of misbehaved members indices (disqualified or inactive).\n // Indices must be in range [1, groupSize], unique, and sorted in ascending\n // order.\n uint8[] misbehavedMembersIndices;\n // Concatenation of signatures from members supporting the result.\n // The message to be signed by each member is keccak256 hash of the\n // calculated group public key, misbehaved members indices and DKG\n // start block. The calculated hash should be prefixed with prefixed with\n // `\\x19Ethereum signed message:\\n` before signing, so the message to\n // sign is:\n // `\\x19Ethereum signed message:\\n${keccak256(\n // groupPubKey, misbehavedMembersIndices, dkgStartBlock\n // )}`\n bytes signatures;\n // Indices of members corresponding to each signature. Indices must be\n // be in range [1, groupSize], unique, and sorted in ascending order.\n uint256[] signingMembersIndices;\n // Identifiers of candidate group members as outputted by the group\n // selection protocol.\n uint32[] members;\n // Keccak256 hash of group members identifiers that actively took part\n // in DKG (excluding IA/DQ members).\n bytes32 membersHash;\n // This struct doesn't contain `__gap` property as the structure is not\n // stored, it is used as a function's calldata argument.\n }\n\n /// @notice States for phases of group creation. The states doesn't include\n /// timeouts which should be tracked and notified individually.\n enum State {\n // Group creation is not in progress. It is a state set after group creation\n // completion either by timeout or by a result approval.\n IDLE,\n // Group creation is awaiting the seed and sortition pool is locked.\n AWAITING_SEED,\n // DKG protocol execution is in progress. A result is being calculated\n // by the clients in this state and the contract awaits a result submission.\n // This is a state to which group creation returns in case of a result\n // challenge notification.\n AWAITING_RESULT,\n // DKG result was submitted and awaits an approval or a challenge. If a result\n // gets challenge the state returns to `AWAITING_RESULT`. If a result gets\n // approval the state changes to `IDLE`.\n CHALLENGE\n }\n\n /// @dev Size of a group in ECDSA wallet.\n uint256 public constant groupSize = 100;\n\n event DkgStarted(uint256 indexed seed);\n\n // To recreate the members that actively took part in dkg, the selected members\n // array should be filtered out from misbehavedMembersIndices.\n event DkgResultSubmitted(\n bytes32 indexed resultHash,\n uint256 indexed seed,\n Result result\n );\n\n event DkgTimedOut();\n\n event DkgResultApproved(\n bytes32 indexed resultHash,\n address indexed approver\n );\n\n event DkgResultChallenged(\n bytes32 indexed resultHash,\n address indexed challenger,\n string reason\n );\n\n event DkgStateLocked();\n\n event DkgSeedTimedOut();\n\n /// @notice Initializes SortitionPool and EcdsaDkgValidator addresses.\n /// Can be performed only once.\n /// @param _sortitionPool Sortition Pool reference\n /// @param _dkgValidator EcdsaDkgValidator reference\n function init(\n Data storage self,\n SortitionPool _sortitionPool,\n EcdsaDkgValidator _dkgValidator\n ) internal {\n require(\n address(self.sortitionPool) == address(0),\n \"Sortition Pool address already set\"\n );\n\n require(\n address(self.dkgValidator) == address(0),\n \"DKG Validator address already set\"\n );\n\n self.sortitionPool = _sortitionPool;\n self.dkgValidator = _dkgValidator;\n }\n\n /// @notice Determines the current state of group creation. It doesn't take\n /// timeouts into consideration. The timeouts should be tracked and\n /// notified separately.\n function currentState(Data storage self)\n internal\n view\n returns (State state)\n {\n state = State.IDLE;\n\n if (self.sortitionPool.isLocked()) {\n state = State.AWAITING_SEED;\n\n if (self.startBlock > 0) {\n state = State.AWAITING_RESULT;\n\n if (self.submittedResultBlock > 0) {\n state = State.CHALLENGE;\n }\n }\n }\n }\n\n /// @notice Locks the sortition pool and starts awaiting for the\n /// group creation seed.\n function lockState(Data storage self) internal {\n require(currentState(self) == State.IDLE, \"Current state is not IDLE\");\n\n emit DkgStateLocked();\n\n self.sortitionPool.lock();\n\n self.stateLockBlock = block.number;\n }\n\n function start(Data storage self, uint256 seed) internal {\n require(\n currentState(self) == State.AWAITING_SEED,\n \"Current state is not AWAITING_SEED\"\n );\n\n emit DkgStarted(seed);\n\n self.startBlock = block.number;\n self.seed = seed;\n }\n\n /// @notice Allows to submit a DKG result. The submitted result does not go\n /// through a validation and before it gets accepted, it needs to\n /// wait through the challenge period during which everyone has\n /// a chance to challenge the result as invalid one. Submitter of\n /// the result needs to be in the sortition pool and if the result\n /// gets challenged, the submitter will get slashed.\n function submitResult(Data storage self, Result calldata result) internal {\n require(\n currentState(self) == State.AWAITING_RESULT,\n \"Current state is not AWAITING_RESULT\"\n );\n require(!hasDkgTimedOut(self), \"DKG timeout already passed\");\n\n SortitionPool sortitionPool = self.sortitionPool;\n\n // Submitter must be an operator in the sortition pool.\n // Declared submitter's member index in the DKG result needs to match\n // the address calling this function.\n require(\n sortitionPool.isOperatorInPool(msg.sender),\n \"Submitter not in the sortition pool\"\n );\n require(\n sortitionPool.getIDOperator(\n result.members[result.submitterMemberIndex - 1]\n ) == msg.sender,\n \"Unexpected submitter index\"\n );\n\n self.submittedResultHash = keccak256(abi.encode(result));\n self.submittedResultBlock = block.number;\n\n emit DkgResultSubmitted(self.submittedResultHash, self.seed, result);\n }\n\n /// @notice Checks if awaiting seed timed out.\n /// @return True if awaiting seed timed out, false otherwise.\n function hasSeedTimedOut(Data storage self) internal view returns (bool) {\n return\n currentState(self) == State.AWAITING_SEED &&\n block.number > (self.stateLockBlock + self.parameters.seedTimeout);\n }\n\n /// @notice Checks if DKG timed out. The DKG timeout period includes time required\n /// for off-chain protocol execution and time for the result publication.\n /// After this time a result cannot be submitted and DKG can be notified\n /// about the timeout. DKG period is adjusted by result submission\n /// offset that include blocks that were mined while invalid result\n /// has been registered until it got challenged.\n /// @return True if DKG timed out, false otherwise.\n function hasDkgTimedOut(Data storage self) internal view returns (bool) {\n return\n currentState(self) == State.AWAITING_RESULT &&\n block.number >\n (self.startBlock +\n self.resultSubmissionStartBlockOffset +\n self.parameters.resultSubmissionTimeout);\n }\n\n /// @notice Notifies about the seed was not delivered and restores the\n /// initial DKG state (IDLE).\n function notifySeedTimeout(Data storage self) internal {\n require(hasSeedTimedOut(self), \"Awaiting seed has not timed out\");\n\n emit DkgSeedTimedOut();\n\n complete(self);\n }\n\n /// @notice Notifies about DKG timeout.\n function notifyDkgTimeout(Data storage self) internal {\n require(hasDkgTimedOut(self), \"DKG has not timed out\");\n\n emit DkgTimedOut();\n\n complete(self);\n }\n\n /// @notice Approves DKG result. Can be called when the challenge period for\n /// the submitted result is finished. Considers the submitted result\n /// as valid. For the first `submitterPrecedencePeriodLength`\n /// blocks after the end of the challenge period can be called only\n /// by the DKG result submitter. After that time, can be called by\n /// anyone.\n /// @dev Can be called after a challenge period for the submitted result.\n /// @param result Result to approve. Must match the submitted result stored\n /// during `submitResult`.\n /// @return misbehavedMembers Identifiers of members who misbehaved during DKG.\n function approveResult(Data storage self, Result calldata result)\n internal\n returns (uint32[] memory misbehavedMembers)\n {\n require(\n currentState(self) == State.CHALLENGE,\n \"Current state is not CHALLENGE\"\n );\n\n uint256 challengePeriodEnd = self.submittedResultBlock +\n self.parameters.resultChallengePeriodLength;\n\n require(\n block.number > challengePeriodEnd,\n \"Challenge period has not passed yet\"\n );\n\n require(\n keccak256(abi.encode(result)) == self.submittedResultHash,\n \"Result under approval is different than the submitted one\"\n );\n\n // Extract submitter member address. Submitter member index is in\n // range [1, groupSize] so we need to -1 when fetching identifier from members\n // array.\n address submitterMember = self.sortitionPool.getIDOperator(\n result.members[result.submitterMemberIndex - 1]\n );\n\n require(\n msg.sender == submitterMember ||\n block.number >\n challengePeriodEnd +\n self.parameters.submitterPrecedencePeriodLength,\n \"Only the DKG result submitter can approve the result at this moment\"\n );\n\n // Extract misbehaved members identifiers. Misbehaved members indices\n // are in range [1, groupSize], so we need to -1 when fetching identifiers from\n // members array.\n misbehavedMembers = new uint32[](\n result.misbehavedMembersIndices.length\n );\n for (uint256 i = 0; i < result.misbehavedMembersIndices.length; i++) {\n misbehavedMembers[i] = result.members[\n result.misbehavedMembersIndices[i] - 1\n ];\n }\n\n emit DkgResultApproved(self.submittedResultHash, msg.sender);\n\n return misbehavedMembers;\n }\n\n /// @notice Challenges DKG result. If the submitted result is proved to be\n /// invalid it reverts the DKG back to the result submission phase.\n /// @dev Can be called during a challenge period for the submitted result.\n /// @param result Result to challenge. Must match the submitted result\n /// stored during `submitResult`.\n /// @return maliciousResultHash Hash of the malicious result.\n /// @return maliciousSubmitter Identifier of the malicious submitter.\n function challengeResult(Data storage self, Result calldata result)\n internal\n returns (bytes32 maliciousResultHash, uint32 maliciousSubmitter)\n {\n require(\n currentState(self) == State.CHALLENGE,\n \"Current state is not CHALLENGE\"\n );\n\n require(\n block.number <=\n self.submittedResultBlock +\n self.parameters.resultChallengePeriodLength,\n \"Challenge period has already passed\"\n );\n\n require(\n keccak256(abi.encode(result)) == self.submittedResultHash,\n \"Result under challenge is different than the submitted one\"\n );\n\n // https://github.com/crytic/slither/issues/982\n // slither-disable-next-line unused-return\n try\n self.dkgValidator.validate(result, self.seed, self.startBlock)\n returns (\n // slither-disable-next-line uninitialized-local,variable-scope\n bool isValid,\n // slither-disable-next-line uninitialized-local,variable-scope\n string memory errorMsg\n ) {\n if (isValid) {\n revert(\"unjustified challenge\");\n }\n\n emit DkgResultChallenged(\n self.submittedResultHash,\n msg.sender,\n errorMsg\n );\n } catch {\n // if the validation reverted we consider the DKG result as invalid\n emit DkgResultChallenged(\n self.submittedResultHash,\n msg.sender,\n \"validation reverted\"\n );\n }\n\n // Consider result hash as malicious.\n maliciousResultHash = self.submittedResultHash;\n maliciousSubmitter = result.members[result.submitterMemberIndex - 1];\n\n // Adjust DKG result submission block start, so submission stage starts\n // from the beginning.\n self.resultSubmissionStartBlockOffset = block.number - self.startBlock;\n\n submittedResultCleanup(self);\n\n return (maliciousResultHash, maliciousSubmitter);\n }\n\n /// @notice Due to EIP150, 1/64 of the gas is not forwarded to the call, and\n /// will be kept to execute the remaining operations in the function\n /// after the call inside the try-catch.\n ///\n /// To ensure there is no way for the caller to manipulate gas limit\n /// in such a way that the call inside try-catch fails with out-of-gas\n /// and the rest of the function is executed with the remaining\n /// 1/64 of gas, we require an extra gas amount to be left at the\n /// end of the call to the function challenging DKG result and\n /// wrapping the call to EcdsaDkgValidator and TokenStaking\n /// contracts inside a try-catch.\n function requireChallengeExtraGas(Data storage self) internal view {\n require(\n gasleft() >= self.parameters.resultChallengeExtraGas,\n \"Not enough extra gas left\"\n );\n }\n\n /// @notice Checks if DKG result is valid for the current DKG.\n /// @param result DKG result.\n /// @return True if the result is valid. If the result is invalid it returns\n /// false and an error message.\n function isResultValid(Data storage self, Result calldata result)\n internal\n view\n returns (bool, string memory)\n {\n require(self.startBlock > 0, \"DKG has not been started\");\n\n return self.dkgValidator.validate(result, self.seed, self.startBlock);\n }\n\n /// @notice Set setSeedTimeout parameter.\n function setSeedTimeout(Data storage self, uint256 newSeedTimeout)\n internal\n {\n require(currentState(self) == State.IDLE, \"Current state is not IDLE\");\n\n require(newSeedTimeout > 0, \"New value should be greater than zero\");\n\n self.parameters.seedTimeout = newSeedTimeout;\n }\n\n /// @notice Set resultChallengePeriodLength parameter.\n function setResultChallengePeriodLength(\n Data storage self,\n uint256 newResultChallengePeriodLength\n ) internal {\n require(currentState(self) == State.IDLE, \"Current state is not IDLE\");\n\n require(\n newResultChallengePeriodLength > 0,\n \"New value should be greater than zero\"\n );\n\n self\n .parameters\n .resultChallengePeriodLength = newResultChallengePeriodLength;\n }\n\n /// @notice Set resultChallengeExtraGas parameter.\n function setResultChallengeExtraGas(\n Data storage self,\n uint256 newResultChallengeExtraGas\n ) internal {\n require(currentState(self) == State.IDLE, \"Current state is not IDLE\");\n\n self.parameters.resultChallengeExtraGas = newResultChallengeExtraGas;\n }\n\n /// @notice Set resultSubmissionTimeout parameter.\n function setResultSubmissionTimeout(\n Data storage self,\n uint256 newResultSubmissionTimeout\n ) internal {\n require(currentState(self) == State.IDLE, \"Current state is not IDLE\");\n\n require(\n newResultSubmissionTimeout > 0,\n \"New value should be greater than zero\"\n );\n\n self.parameters.resultSubmissionTimeout = newResultSubmissionTimeout;\n }\n\n /// @notice Set submitterPrecedencePeriodLength parameter.\n function setSubmitterPrecedencePeriodLength(\n Data storage self,\n uint256 newSubmitterPrecedencePeriodLength\n ) internal {\n require(currentState(self) == State.IDLE, \"Current state is not IDLE\");\n\n require(\n newSubmitterPrecedencePeriodLength <\n self.parameters.resultSubmissionTimeout,\n \"New value should be less than result submission period length\"\n );\n\n self\n .parameters\n .submitterPrecedencePeriodLength = newSubmitterPrecedencePeriodLength;\n }\n\n /// @notice Completes DKG by cleaning up state.\n /// @dev Should be called after DKG times out or a result is approved.\n function complete(Data storage self) internal {\n delete self.startBlock;\n delete self.seed;\n delete self.resultSubmissionStartBlockOffset;\n submittedResultCleanup(self);\n self.sortitionPool.unlock();\n }\n\n /// @notice Cleans up submitted result state either after DKG completion\n /// (as part of `complete` method) or after justified challenge.\n function submittedResultCleanup(Data storage self) private {\n delete self.submittedResultHash;\n delete self.submittedResultBlock;\n }\n}\n" + }, + "@keep-network/ecdsa/contracts/libraries/EcdsaInactivity.sol": { + "content": "// SPDX-License-Identifier: GPL-3.0-only\n//\n// ▓▓▌ ▓▓ ▐▓▓ ▓▓▓▓▓▓▓▓▓▓▌▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▄\n// ▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▌▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓\n// ▓▓▓▓▓▓ ▓▓▓▓▓▓▓▀ ▐▓▓▓▓▓▓ ▐▓▓▓▓▓ ▓▓▓▓▓▓ ▓▓▓▓▓ ▐▓▓▓▓▓▌ ▐▓▓▓▓▓▓\n// ▓▓▓▓▓▓▄▄▓▓▓▓▓▓▓▀ ▐▓▓▓▓▓▓▄▄▄▄ ▓▓▓▓▓▓▄▄▄▄ ▐▓▓▓▓▓▌ ▐▓▓▓▓▓▓\n// ▓▓▓▓▓▓▓▓▓▓▓▓▓▀ ▐▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓\n// ▓▓▓▓▓▓▀▀▓▓▓▓▓▓▄ ▐▓▓▓▓▓▓▀▀▀▀ ▓▓▓▓▓▓▀▀▀▀ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▀\n// ▓▓▓▓▓▓ ▀▓▓▓▓▓▓▄ ▐▓▓▓▓▓▓ ▓▓▓▓▓ ▓▓▓▓▓▓ ▓▓▓▓▓ ▐▓▓▓▓▓▌\n// ▓▓▓▓▓▓▓▓▓▓ █▓▓▓▓▓▓▓▓▓ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓\n// ▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓\n//\n// Trust math, not hardware.\n\npragma solidity 0.8.17;\n\nimport \"@openzeppelin/contracts-upgradeable/utils/cryptography/ECDSAUpgradeable.sol\";\n\nimport \"@keep-network/random-beacon/contracts/libraries/BytesLib.sol\";\nimport \"@keep-network/sortition-pools/contracts/SortitionPool.sol\";\n\nimport \"./Wallets.sol\";\n\nlibrary EcdsaInactivity {\n using BytesLib for bytes;\n using ECDSAUpgradeable for bytes32;\n\n struct Claim {\n // ID of the wallet whose signing group is raising the inactivity claim.\n bytes32 walletID;\n // Indices of group members accused of being inactive. Indices must be in\n // range [1, groupMembers.length], unique, and sorted in ascending order.\n uint256[] inactiveMembersIndices;\n // Indicates if inactivity claim is a wallet-wide heartbeat failure.\n // If wallet failed a heartbeat, this is signalled to the wallet owner\n // who may decide to move responsibilities to another wallet\n // given that the wallet who failed the heartbeat is at risk of not\n // being able to sign messages soon.\n bool heartbeatFailed;\n // Concatenation of signatures from members supporting the claim.\n // The message to be signed by each member is keccak256 hash of the\n // concatenation of the chain ID, inactivity claim nonce for the given\n // wallet, wallet public key, inactive members indices, and boolean flag\n // indicating if this is a wallet-wide heartbeat failure. The calculated\n // hash should be prefixed with `\\x19Ethereum signed message:\\n` before\n // signing, so the message to sign is:\n // `\\x19Ethereum signed message:\\n${keccak256(\n // chainID | nonce | walletPubKey | inactiveMembersIndices | heartbeatFailed\n // )}`\n bytes signatures;\n // Indices of members corresponding to each signature. Indices must be\n // in range [1, groupMembers.length], unique, and sorted in ascending\n // order.\n uint256[] signingMembersIndices;\n // This struct doesn't contain `__gap` property as the structure is not\n // stored, it is used as a function's calldata argument.\n }\n\n /// @notice The minimum number of wallet signing group members needed to\n /// interact according to the protocol to produce a valid inactivity\n /// claim.\n uint256 public constant groupThreshold = 51;\n\n /// @notice Size in bytes of a single signature produced by member\n /// supporting the inactivity claim.\n uint256 public constant signatureByteSize = 65;\n\n /// @notice Verifies the inactivity claim according to the rules defined in\n /// `Claim` struct documentation. Reverts if verification fails.\n /// @dev Wallet signing group members hash is validated upstream in\n /// `WalletRegistry.notifyOperatorInactivity()`\n /// @param sortitionPool Sortition pool reference\n /// @param claim Inactivity claim\n /// @param walletPubKey Public key of the wallet\n /// @param nonce Current inactivity nonce for wallet used in the claim\n /// @param groupMembers Identifiers of group members\n /// @return inactiveMembers Identifiers of members who are inactive\n function verifyClaim(\n SortitionPool sortitionPool,\n Claim calldata claim,\n bytes memory walletPubKey,\n uint256 nonce,\n uint32[] calldata groupMembers\n ) external view returns (uint32[] memory inactiveMembers) {\n // Validate inactive members indices. Maximum indices count is equal to\n // the group size and is not limited deliberately to leave a theoretical\n // possibility to accuse more members than `groupSize - groupThreshold`.\n validateMembersIndices(\n claim.inactiveMembersIndices,\n groupMembers.length\n );\n\n // Validate signatures array is properly formed and number of\n // signatures and signers is correct.\n uint256 signaturesCount = claim.signatures.length / signatureByteSize;\n require(claim.signatures.length != 0, \"No signatures provided\");\n require(\n claim.signatures.length % signatureByteSize == 0,\n \"Malformed signatures array\"\n );\n require(\n signaturesCount == claim.signingMembersIndices.length,\n \"Unexpected signatures count\"\n );\n require(signaturesCount >= groupThreshold, \"Too few signatures\");\n require(signaturesCount <= groupMembers.length, \"Too many signatures\");\n\n // Validate signing members indices. Note that `signingMembersIndices`\n // were already partially validated during `signatures` parameter\n // validation.\n validateMembersIndices(\n claim.signingMembersIndices,\n groupMembers.length\n );\n\n bytes32 signedMessageHash = keccak256(\n abi.encode(\n block.chainid,\n nonce,\n walletPubKey,\n claim.inactiveMembersIndices,\n claim.heartbeatFailed\n )\n ).toEthSignedMessageHash();\n\n address[] memory groupMembersAddresses = sortitionPool.getIDOperators(\n groupMembers\n );\n\n // Verify each signature.\n bytes memory checkedSignature;\n bool senderSignatureExists = false;\n for (uint256 i = 0; i < signaturesCount; i++) {\n uint256 memberIndex = claim.signingMembersIndices[i];\n checkedSignature = claim.signatures.slice(\n signatureByteSize * i,\n signatureByteSize\n );\n address recoveredAddress = signedMessageHash.recover(\n checkedSignature\n );\n\n require(\n groupMembersAddresses[memberIndex - 1] == recoveredAddress,\n \"Invalid signature\"\n );\n\n if (!senderSignatureExists && msg.sender == recoveredAddress) {\n senderSignatureExists = true;\n }\n }\n\n require(senderSignatureExists, \"Sender must be claim signer\");\n\n inactiveMembers = new uint32[](claim.inactiveMembersIndices.length);\n for (uint256 i = 0; i < claim.inactiveMembersIndices.length; i++) {\n uint256 memberIndex = claim.inactiveMembersIndices[i];\n inactiveMembers[i] = groupMembers[memberIndex - 1];\n }\n\n return inactiveMembers;\n }\n\n /// @notice Validates members indices array. Array is considered valid\n /// if its size and each single index are in [1, groupSize] range,\n /// indexes are unique, and sorted in an ascending order.\n /// Reverts if validation fails.\n /// @param indices Array to validate.\n /// @param groupSize Group size used as reference.\n function validateMembersIndices(\n uint256[] calldata indices,\n uint256 groupSize\n ) internal pure {\n require(\n indices.length > 0 && indices.length <= groupSize,\n \"Corrupted members indices\"\n );\n\n // Check if first and last indices are in range [1, groupSize].\n // This check combined with the loop below makes sure every single\n // index is in the correct range.\n require(\n indices[0] > 0 && indices[indices.length - 1] <= groupSize,\n \"Corrupted members indices\"\n );\n\n for (uint256 i = 0; i < indices.length - 1; i++) {\n // Check whether given index is smaller than the next one. This\n // way we are sure indexes are ordered in the ascending order\n // and there are no duplicates.\n require(indices[i] < indices[i + 1], \"Corrupted members indices\");\n }\n }\n}\n" + }, + "@keep-network/ecdsa/contracts/libraries/Wallets.sol": { + "content": "// SPDX-License-Identifier: GPL-3.0-only\n//\n// ▓▓▌ ▓▓ ▐▓▓ ▓▓▓▓▓▓▓▓▓▓▌▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▄\n// ▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▌▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓\n// ▓▓▓▓▓▓ ▓▓▓▓▓▓▓▀ ▐▓▓▓▓▓▓ ▐▓▓▓▓▓ ▓▓▓▓▓▓ ▓▓▓▓▓ ▐▓▓▓▓▓▌ ▐▓▓▓▓▓▓\n// ▓▓▓▓▓▓▄▄▓▓▓▓▓▓▓▀ ▐▓▓▓▓▓▓▄▄▄▄ ▓▓▓▓▓▓▄▄▄▄ ▐▓▓▓▓▓▌ ▐▓▓▓▓▓▓\n// ▓▓▓▓▓▓▓▓▓▓▓▓▓▀ ▐▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓\n// ▓▓▓▓▓▓▀▀▓▓▓▓▓▓▄ ▐▓▓▓▓▓▓▀▀▀▀ ▓▓▓▓▓▓▀▀▀▀ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▀\n// ▓▓▓▓▓▓ ▀▓▓▓▓▓▓▄ ▐▓▓▓▓▓▓ ▓▓▓▓▓ ▓▓▓▓▓▓ ▓▓▓▓▓ ▐▓▓▓▓▓▌\n// ▓▓▓▓▓▓▓▓▓▓ █▓▓▓▓▓▓▓▓▓ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓\n// ▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓\n//\n// Trust math, not hardware.\n\npragma solidity 0.8.17;\n\nlibrary Wallets {\n struct Wallet {\n // Keccak256 hash of group members identifiers array. Group members do not\n // include operators selected by the sortition pool that misbehaved during DKG.\n bytes32 membersIdsHash;\n // Uncompressed ECDSA public key stored as X and Y coordinates (32 bytes each).\n bytes32 publicKeyX;\n bytes32 publicKeyY;\n // This struct doesn't contain `__gap` property as the structure is stored\n // in a mapping, mappings store values in different slots and they are\n // not contiguous with other values.\n }\n\n struct Data {\n // Mapping of keccak256 hashes of wallet public keys to wallet details.\n // Hash of public key is considered an unique wallet identifier.\n mapping(bytes32 => Wallet) registry;\n // Reserved storage space in case we need to add more variables.\n // See https://docs.openzeppelin.com/contracts/4.x/upgradeable#storage_gaps\n // slither-disable-next-line unused-state\n uint256[49] __gap;\n }\n\n /// @notice Performs preliminary validation of a new group public key.\n /// The group public key must be unique and have 64 bytes in length.\n /// If the validation fails, the function reverts. This function\n /// must be called first for a public key of a wallet added with\n /// `addWallet` function.\n /// @param publicKey Uncompressed public key of a new wallet.\n function validatePublicKey(Data storage self, bytes calldata publicKey)\n internal\n view\n {\n require(publicKey.length == 64, \"Invalid length of the public key\");\n\n bytes32 walletID = keccak256(publicKey);\n require(\n self.registry[walletID].publicKeyX == bytes32(0),\n \"Wallet with the given public key already exists\"\n );\n\n bytes32 publicKeyX = bytes32(publicKey[:32]);\n require(publicKeyX != bytes32(0), \"Wallet public key must be non-zero\");\n }\n\n /// @notice Registers a new wallet. This function does not validate\n /// parameters. The code calling this function must call\n /// `validatePublicKey` first.\n /// @dev Uses a public key hash as a unique identifier of a wallet.\n /// @param membersIdsHash Keccak256 hash of group members identifiers array\n /// @param publicKey Uncompressed public key\n /// @return walletID Wallet's ID\n /// @return publicKeyX Wallet's public key's X coordinate\n /// @return publicKeyY Wallet's public key's Y coordinate\n function addWallet(\n Data storage self,\n bytes32 membersIdsHash,\n bytes calldata publicKey\n )\n internal\n returns (\n bytes32 walletID,\n bytes32 publicKeyX,\n bytes32 publicKeyY\n )\n {\n walletID = keccak256(publicKey);\n\n publicKeyX = bytes32(publicKey[:32]);\n publicKeyY = bytes32(publicKey[32:]);\n\n self.registry[walletID].membersIdsHash = membersIdsHash;\n self.registry[walletID].publicKeyX = publicKeyX;\n self.registry[walletID].publicKeyY = publicKeyY;\n }\n\n /// @notice Deletes wallet with the given ID from the registry. Reverts\n /// if wallet with the given ID has not been registered or if it\n /// has already been closed.\n function deleteWallet(Data storage self, bytes32 walletID) internal {\n require(\n isWalletRegistered(self, walletID),\n \"Wallet with the given ID has not been registered\"\n );\n\n delete self.registry[walletID];\n }\n\n /// @notice Checks if a wallet with the given ID is registered.\n /// @param walletID Wallet's ID\n /// @return True if a wallet is registered, false otherwise\n function isWalletRegistered(Data storage self, bytes32 walletID)\n internal\n view\n returns (bool)\n {\n return self.registry[walletID].publicKeyX != bytes32(0);\n }\n\n /// @notice Returns Keccak256 hash of the wallet signing group members\n /// identifiers array. Group members do not include operators\n /// selected by the sortition pool that misbehaved during DKG.\n /// Reverts if wallet with the given ID is not registered.\n /// @param walletID ID of the wallet\n /// @return Wallet signing group members hash\n function getWalletMembersIdsHash(Data storage self, bytes32 walletID)\n internal\n view\n returns (bytes32)\n {\n require(\n isWalletRegistered(self, walletID),\n \"Wallet with the given ID has not been registered\"\n );\n\n return self.registry[walletID].membersIdsHash;\n }\n\n /// @notice Gets public key of a wallet with the given wallet ID.\n /// The public key is returned as X and Y coordinates.\n /// Reverts if wallet with the given ID is not registered.\n /// @param walletID ID of the wallet\n /// @return x Public key X coordinate\n /// @return y Public key Y coordinate\n function getWalletPublicKeyCoordinates(Data storage self, bytes32 walletID)\n internal\n view\n returns (bytes32 x, bytes32 y)\n {\n require(\n isWalletRegistered(self, walletID),\n \"Wallet with the given ID has not been registered\"\n );\n\n Wallet storage wallet = self.registry[walletID];\n\n return (wallet.publicKeyX, wallet.publicKeyY);\n }\n\n /// @notice Gets public key of a wallet with the given wallet ID.\n /// The public key is returned in an uncompressed format as a 64-byte\n /// concatenation of X and Y coordinates.\n /// Reverts if wallet with the given ID is not registered.\n /// @param walletID ID of the wallet\n /// @return Uncompressed public key of the wallet\n function getWalletPublicKey(Data storage self, bytes32 walletID)\n internal\n view\n returns (bytes memory)\n {\n (bytes32 x, bytes32 y) = getWalletPublicKeyCoordinates(self, walletID);\n return bytes.concat(x, y);\n }\n}\n" + }, + "@keep-network/ecdsa/contracts/WalletRegistry.sol": { + "content": "// SPDX-License-Identifier: GPL-3.0-only\n//\n// ▓▓▌ ▓▓ ▐▓▓ ▓▓▓▓▓▓▓▓▓▓▌▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▄\n// ▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▌▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓\n// ▓▓▓▓▓▓ ▓▓▓▓▓▓▓▀ ▐▓▓▓▓▓▓ ▐▓▓▓▓▓ ▓▓▓▓▓▓ ▓▓▓▓▓ ▐▓▓▓▓▓▌ ▐▓▓▓▓▓▓\n// ▓▓▓▓▓▓▄▄▓▓▓▓▓▓▓▀ ▐▓▓▓▓▓▓▄▄▄▄ ▓▓▓▓▓▓▄▄▄▄ ▐▓▓▓▓▓▌ ▐▓▓▓▓▓▓\n// ▓▓▓▓▓▓▓▓▓▓▓▓▓▀ ▐▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓\n// ▓▓▓▓▓▓▀▀▓▓▓▓▓▓▄ ▐▓▓▓▓▓▓▀▀▀▀ ▓▓▓▓▓▓▀▀▀▀ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▀\n// ▓▓▓▓▓▓ ▀▓▓▓▓▓▓▄ ▐▓▓▓▓▓▓ ▓▓▓▓▓ ▓▓▓▓▓▓ ▓▓▓▓▓ ▐▓▓▓▓▓▌\n// ▓▓▓▓▓▓▓▓▓▓ █▓▓▓▓▓▓▓▓▓ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓\n// ▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓\n//\n// Trust math, not hardware.\n\npragma solidity 0.8.17;\n\nimport \"./api/IWalletRegistry.sol\";\nimport \"./api/IWalletOwner.sol\";\nimport \"./libraries/Wallets.sol\";\nimport {EcdsaAuthorization as Authorization} from \"./libraries/EcdsaAuthorization.sol\";\nimport {EcdsaDkg as DKG} from \"./libraries/EcdsaDkg.sol\";\nimport {EcdsaInactivity as Inactivity} from \"./libraries/EcdsaInactivity.sol\";\nimport {EcdsaDkgValidator as DKGValidator} from \"./EcdsaDkgValidator.sol\";\n\nimport \"@keep-network/sortition-pools/contracts/SortitionPool.sol\";\nimport \"@keep-network/random-beacon/contracts/api/IRandomBeacon.sol\";\nimport \"@keep-network/random-beacon/contracts/api/IRandomBeaconConsumer.sol\";\nimport \"@keep-network/random-beacon/contracts/Reimbursable.sol\";\nimport \"@keep-network/random-beacon/contracts/ReimbursementPool.sol\";\nimport \"@keep-network/random-beacon/contracts/Governable.sol\";\n\nimport \"@threshold-network/solidity-contracts/contracts/staking/IApplication.sol\";\nimport \"@threshold-network/solidity-contracts/contracts/staking/IStaking.sol\";\n\nimport \"@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol\";\n\ncontract WalletRegistry is\n IWalletRegistry,\n IRandomBeaconConsumer,\n IApplication,\n Governable,\n Reimbursable,\n Initializable\n{\n using Authorization for Authorization.Data;\n using DKG for DKG.Data;\n using Wallets for Wallets.Data;\n\n // Libraries data storages\n Authorization.Data internal authorization;\n DKG.Data internal dkg;\n Wallets.Data internal wallets;\n\n /// @notice Slashing amount for submitting a malicious DKG result. Every\n /// DKG result submitted can be challenged for the time of\n /// `dkg.resultChallengePeriodLength`. If the DKG result submitted\n /// is challenged and proven to be malicious, the operator who\n /// submitted the malicious result is slashed for\n /// `_maliciousDkgResultSlashingAmount`.\n uint96 internal _maliciousDkgResultSlashingAmount;\n\n /// @notice Percentage of the staking contract malicious behavior\n /// notification reward which will be transferred to the notifier\n /// reporting about a malicious DKG result. Notifiers are rewarded\n /// from a notifiers treasury pool. For example, if\n /// notification reward is 1000 and the value of the multiplier is\n /// 5, the notifier will receive: 5% of 1000 = 50 per each\n /// operator affected.\n uint256 internal _maliciousDkgResultNotificationRewardMultiplier;\n\n /// @notice Duration of the sortition pool rewards ban imposed on operators\n /// who missed their turn for DKG result submission or who failed\n /// a heartbeat.\n uint256 internal _sortitionPoolRewardsBanDuration;\n\n /// @notice Calculated max gas cost for submitting a DKG result. This will\n /// be refunded as part of the DKG approval process. It is in the\n /// submitter's interest to not skip his priority turn on the approval,\n /// otherwise the refund of the DKG submission will be refunded to\n /// another group member that will call the DKG approve function.\n uint256 internal _dkgResultSubmissionGas;\n\n /// @notice Gas that is meant to balance the DKG result approval's overall\n /// cost. It can be updated by the governance based on the current\n /// market conditions.\n uint256 internal _dkgResultApprovalGasOffset;\n\n /// @notice Gas that is meant to balance the notification of an operator\n /// inactivity. It can be updated by the governance based on the\n /// current market conditions.\n uint256 internal _notifyOperatorInactivityGasOffset;\n\n /// @notice Gas that is meant to balance the notification of a seed for DKG\n /// delivery timeout. It can be updated by the governance based on the\n /// current market conditions.\n uint256 internal _notifySeedTimeoutGasOffset;\n\n /// @notice Gas that is meant to balance the notification of a DKG protocol\n /// execution timeout. It can be updated by the governance based on the\n /// current market conditions.\n /// @dev The value is subtracted for the refundable gas calculation, as the\n /// DKG timeout notification transaction recovers some gas when cleaning\n /// up the storage.\n uint256 internal _notifyDkgTimeoutNegativeGasOffset;\n\n /// @notice Stores current operator inactivity claim nonce for the given\n /// wallet signing group. Each claim is made with a unique nonce\n /// which protects against claim replay.\n mapping(bytes32 => uint256) public inactivityClaimNonce; // walletID -> nonce\n\n // Address that is set as owner of all wallets. Only this address can request\n // new wallets creation and manage their state.\n IWalletOwner public walletOwner;\n\n // External dependencies\n\n /// @custom:oz-upgrades-unsafe-allow state-variable-immutable\n SortitionPool public immutable sortitionPool;\n /// @custom:oz-upgrades-unsafe-allow state-variable-immutable\n IStaking public immutable staking;\n IRandomBeacon public randomBeacon;\n\n // Events\n event DkgStarted(uint256 indexed seed);\n\n event DkgResultSubmitted(\n bytes32 indexed resultHash,\n uint256 indexed seed,\n DKG.Result result\n );\n\n event DkgTimedOut();\n\n event DkgResultApproved(\n bytes32 indexed resultHash,\n address indexed approver\n );\n\n event DkgResultChallenged(\n bytes32 indexed resultHash,\n address indexed challenger,\n string reason\n );\n\n event DkgStateLocked();\n\n event DkgSeedTimedOut();\n\n event WalletCreated(\n bytes32 indexed walletID,\n bytes32 indexed dkgResultHash\n );\n\n event WalletClosed(bytes32 indexed walletID);\n\n event DkgMaliciousResultSlashed(\n bytes32 indexed resultHash,\n uint256 slashingAmount,\n address maliciousSubmitter\n );\n\n event DkgMaliciousResultSlashingFailed(\n bytes32 indexed resultHash,\n uint256 slashingAmount,\n address maliciousSubmitter\n );\n\n event AuthorizationParametersUpdated(\n uint96 minimumAuthorization,\n uint64 authorizationDecreaseDelay,\n uint64 authorizationDecreaseChangePeriod\n );\n\n event RewardParametersUpdated(\n uint256 maliciousDkgResultNotificationRewardMultiplier,\n uint256 sortitionPoolRewardsBanDuration\n );\n\n event SlashingParametersUpdated(uint256 maliciousDkgResultSlashingAmount);\n\n event DkgParametersUpdated(\n uint256 seedTimeout,\n uint256 resultChallengePeriodLength,\n uint256 resultChallengeExtraGas,\n uint256 resultSubmissionTimeout,\n uint256 resultSubmitterPrecedencePeriodLength\n );\n\n event GasParametersUpdated(\n uint256 dkgResultSubmissionGas,\n uint256 dkgResultApprovalGasOffset,\n uint256 notifyOperatorInactivityGasOffset,\n uint256 notifySeedTimeoutGasOffset,\n uint256 notifyDkgTimeoutNegativeGasOffset\n );\n\n event RandomBeaconUpgraded(address randomBeacon);\n\n event WalletOwnerUpdated(address walletOwner);\n\n event OperatorRegistered(\n address indexed stakingProvider,\n address indexed operator\n );\n\n event AuthorizationIncreased(\n address indexed stakingProvider,\n address indexed operator,\n uint96 fromAmount,\n uint96 toAmount\n );\n\n event AuthorizationDecreaseRequested(\n address indexed stakingProvider,\n address indexed operator,\n uint96 fromAmount,\n uint96 toAmount,\n uint64 decreasingAt\n );\n\n event AuthorizationDecreaseApproved(address indexed stakingProvider);\n\n event InvoluntaryAuthorizationDecreaseFailed(\n address indexed stakingProvider,\n address indexed operator,\n uint96 fromAmount,\n uint96 toAmount\n );\n\n event OperatorJoinedSortitionPool(\n address indexed stakingProvider,\n address indexed operator\n );\n\n event OperatorStatusUpdated(\n address indexed stakingProvider,\n address indexed operator\n );\n\n event InactivityClaimed(\n bytes32 indexed walletID,\n uint256 nonce,\n address notifier\n );\n\n modifier onlyStakingContract() {\n require(\n msg.sender == address(staking),\n \"Caller is not the staking contract\"\n );\n _;\n }\n\n /// @notice Reverts if called not by the Wallet Owner.\n modifier onlyWalletOwner() {\n require(\n msg.sender == address(walletOwner),\n \"Caller is not the Wallet Owner\"\n );\n _;\n }\n\n modifier onlyReimbursableAdmin() override {\n require(governance == msg.sender, \"Caller is not the governance\");\n _;\n }\n\n /// @dev Used to initialize immutable variables only, use `initialize` function\n /// for upgradable contract initialization on deployment.\n /// @custom:oz-upgrades-unsafe-allow constructor\n constructor(SortitionPool _sortitionPool, IStaking _staking) {\n sortitionPool = _sortitionPool;\n staking = _staking;\n\n _disableInitializers();\n }\n\n /// @dev Initializes upgradable contract on deployment.\n function initialize(\n DKGValidator _ecdsaDkgValidator,\n IRandomBeacon _randomBeacon,\n ReimbursementPool _reimbursementPool\n ) external initializer {\n randomBeacon = _randomBeacon;\n reimbursementPool = _reimbursementPool;\n\n _transferGovernance(msg.sender);\n\n //\n // All parameters set in the constructor are initial ones, used at the\n // moment contracts were deployed for the first time. Parameters are\n // governable and values assigned in the constructor do not need to\n // reflect the current ones.\n //\n\n // Minimum authorization is 40k T.\n //\n // Authorization decrease delay is 45 days.\n //\n // Authorization decrease change period is 45 days. It means pending\n // authorization decrease can be overwritten all the time.\n authorization.setMinimumAuthorization(40_000e18);\n authorization.setAuthorizationDecreaseDelay(3_888_000);\n authorization.setAuthorizationDecreaseChangePeriod(3_888_000);\n\n // Malicious DKG result slashing amount is set initially to 1% of the\n // minimum authorization (400 T). This values needs to be increased\n // significantly once the system is fully launched.\n //\n // Notifier of a malicious DKG result receives 100% of the notifier\n // reward from the staking contract.\n //\n // Inactive operators are set as ineligible for rewards for 2 weeks.\n _maliciousDkgResultSlashingAmount = 400e18;\n _maliciousDkgResultNotificationRewardMultiplier = 100;\n _sortitionPoolRewardsBanDuration = 2 weeks;\n\n // DKG seed timeout is set to 48h assuming 15s block time. The same\n // value is used by the Random Beacon as a relay entry hard timeout.\n //\n // DKG result challenge period length is set to 48h as well, assuming\n // 15s block time.\n //\n // DKG result submission timeout covers:\n // - 20 blocks required to confirm the DkgStarted event off-chain\n // - 5 retries of the off-chain protocol that takes 211 blocks at most\n // - 15 blocks to submit the result for each of the 100 members\n // That gives: 20 + (5 * 211) + (15 * 100) = 2575\n //\n //\n // The original DKG result submitter has 20 blocks to approve it before\n // anyone else can do that.\n //\n // With these parameters, the happy path takes no more than 104 hours.\n // In practice, it should take about 48 hours (just the challenge time).\n dkg.init(sortitionPool, _ecdsaDkgValidator);\n dkg.setSeedTimeout(11_520);\n dkg.setResultChallengePeriodLength(11_520);\n dkg.setResultChallengeExtraGas(50_000);\n dkg.setResultSubmissionTimeout(2575);\n dkg.setSubmitterPrecedencePeriodLength(20);\n\n // Gas parameters were adjusted based on Ethereum state in April 2022.\n // If the cost of EVM opcodes change over time, these parameters will\n // have to be updated.\n _dkgResultSubmissionGas = 290_000;\n _dkgResultApprovalGasOffset = 72_000;\n _notifyOperatorInactivityGasOffset = 93_000;\n _notifySeedTimeoutGasOffset = 7_250;\n _notifyDkgTimeoutNegativeGasOffset = 2_300;\n }\n\n /// @notice Withdraws application rewards for the given staking provider.\n /// Rewards are withdrawn to the staking provider's beneficiary\n /// address set in the staking contract. Reverts if staking provider\n /// has not registered the operator address.\n /// @dev Emits `RewardsWithdrawn` event.\n function withdrawRewards(address stakingProvider) external {\n address operator = stakingProviderToOperator(stakingProvider);\n require(operator != address(0), \"Unknown operator\");\n (, address beneficiary, ) = staking.rolesOf(stakingProvider);\n uint96 amount = sortitionPool.withdrawRewards(operator, beneficiary);\n // slither-disable-next-line reentrancy-events\n emit RewardsWithdrawn(stakingProvider, amount);\n }\n\n /// @notice Withdraws rewards belonging to operators marked as ineligible\n /// for sortition pool rewards.\n /// @dev Can be called only by the contract guvnor, which should be the\n /// wallet registry governance contract.\n /// @param recipient Recipient of withdrawn rewards.\n function withdrawIneligibleRewards(address recipient)\n external\n onlyGovernance\n {\n sortitionPool.withdrawIneligible(recipient);\n }\n\n /// @notice Used by staking provider to set operator address that will\n /// operate ECDSA node. The given staking provider can set operator\n /// address only one time. The operator address can not be changed\n /// and must be unique. Reverts if the operator is already set for\n /// the staking provider or if the operator address is already in\n /// use. Reverts if there is a pending authorization decrease for\n /// the staking provider.\n function registerOperator(address operator) external {\n authorization.registerOperator(operator);\n }\n\n /// @notice Lets the operator join the sortition pool. The operator address\n /// must be known - before calling this function, it has to be\n /// appointed by the staking provider by calling `registerOperator`.\n /// Also, the operator must have the minimum authorization required\n /// by ECDSA. Function reverts if there is no minimum stake\n /// authorized or if the operator is not known. If there was an\n /// authorization decrease requested, it is activated by starting\n /// the authorization decrease delay.\n function joinSortitionPool() external {\n authorization.joinSortitionPool(staking, sortitionPool);\n }\n\n /// @notice Updates status of the operator in the sortition pool. If there\n /// was an authorization decrease requested, it is activated by\n /// starting the authorization decrease delay.\n /// Function reverts if the operator is not known.\n function updateOperatorStatus(address operator) external {\n authorization.updateOperatorStatus(staking, sortitionPool, operator);\n }\n\n /// @notice Used by T staking contract to inform the application that the\n /// authorized stake amount for the given staking provider increased.\n ///\n /// Reverts if the authorization amount is below the minimum.\n ///\n /// The function is not updating the sortition pool. Sortition pool\n /// state needs to be updated by the operator with a call to\n /// `joinSortitionPool` or `updateOperatorStatus`.\n ///\n /// @dev Can only be called by T staking contract.\n function authorizationIncreased(\n address stakingProvider,\n uint96 fromAmount,\n uint96 toAmount\n ) external onlyStakingContract {\n authorization.authorizationIncreased(\n stakingProvider,\n fromAmount,\n toAmount\n );\n }\n\n /// @notice Used by T staking contract to inform the application that the\n /// authorization decrease for the given staking provider has been\n /// requested.\n ///\n /// Reverts if the amount after deauthorization would be non-zero\n /// and lower than the minimum authorization.\n ///\n /// If the operator is not known (`registerOperator` was not called)\n /// it lets to `approveAuthorizationDecrease` immediatelly. If the\n /// operator is known (`registerOperator` was called), the operator\n /// needs to update state of the sortition pool with a call to\n /// `joinSortitionPool` or `updateOperatorStatus`. After the\n /// sortition pool state is in sync, authorization decrease delay\n /// starts.\n ///\n /// After authorization decrease delay passes, authorization\n /// decrease request needs to be approved with a call to\n /// `approveAuthorizationDecrease` function.\n ///\n /// If there is a pending authorization decrease request, it is\n /// overwritten.\n ///\n /// @dev Can only be called by T staking contract.\n function authorizationDecreaseRequested(\n address stakingProvider,\n uint96 fromAmount,\n uint96 toAmount\n ) external onlyStakingContract {\n authorization.authorizationDecreaseRequested(\n stakingProvider,\n fromAmount,\n toAmount\n );\n }\n\n /// @notice Approves the previously registered authorization decrease\n /// request. Reverts if authorization decrease delay has not passed\n /// yet or if the authorization decrease was not requested for the\n /// given staking provider.\n function approveAuthorizationDecrease(address stakingProvider) external {\n authorization.approveAuthorizationDecrease(staking, stakingProvider);\n }\n\n /// @notice Used by T staking contract to inform the application the\n /// authorization has been decreased for the given staking provider\n /// involuntarily, as a result of slashing.\n ///\n /// If the operator is not known (`registerOperator` was not called)\n /// the function does nothing. The operator was never in a sortition\n /// pool so there is nothing to update.\n ///\n /// If the operator is known, sortition pool is unlocked, and the\n /// operator is in the sortition pool, the sortition pool state is\n /// updated. If the sortition pool is locked, update needs to be\n /// postponed. Every other staker is incentivized to call\n /// `updateOperatorStatus` for the problematic operator to increase\n /// their own rewards in the pool.\n function involuntaryAuthorizationDecrease(\n address stakingProvider,\n uint96 fromAmount,\n uint96 toAmount\n ) external onlyStakingContract {\n authorization.involuntaryAuthorizationDecrease(\n staking,\n sortitionPool,\n stakingProvider,\n fromAmount,\n toAmount\n );\n }\n\n /// @notice Updates address of the Random Beacon.\n /// @dev Can be called only by the contract guvnor, which should be the\n /// wallet registry governance contract. The caller is responsible for\n /// validating parameters.\n /// @param _randomBeacon Random Beacon address.\n function upgradeRandomBeacon(IRandomBeacon _randomBeacon)\n external\n onlyGovernance\n {\n randomBeacon = _randomBeacon;\n emit RandomBeaconUpgraded(address(_randomBeacon));\n }\n\n /// @notice Updates the wallet owner.\n /// @dev Can be called only by the contract guvnor, which should be the\n /// wallet registry governance contract. The caller is responsible for\n /// validating parameters. The wallet owner has to implement `IWalletOwner`\n /// interface.\n /// @param _walletOwner New wallet owner address.\n function updateWalletOwner(IWalletOwner _walletOwner)\n external\n onlyGovernance\n {\n walletOwner = _walletOwner;\n emit WalletOwnerUpdated(address(_walletOwner));\n }\n\n /// @notice Updates the values of authorization parameters.\n /// @dev Can be called only by the contract guvnor, which should be the\n /// wallet registry governance contract. The caller is responsible for\n /// validating parameters.\n /// @param _minimumAuthorization New minimum authorization amount.\n /// @param _authorizationDecreaseDelay New authorization decrease delay in\n /// seconds.\n /// @param _authorizationDecreaseChangePeriod New authorization decrease\n /// change period in seconds.\n function updateAuthorizationParameters(\n uint96 _minimumAuthorization,\n uint64 _authorizationDecreaseDelay,\n uint64 _authorizationDecreaseChangePeriod\n ) external onlyGovernance {\n authorization.setMinimumAuthorization(_minimumAuthorization);\n authorization.setAuthorizationDecreaseDelay(\n _authorizationDecreaseDelay\n );\n authorization.setAuthorizationDecreaseChangePeriod(\n _authorizationDecreaseChangePeriod\n );\n\n emit AuthorizationParametersUpdated(\n _minimumAuthorization,\n _authorizationDecreaseDelay,\n _authorizationDecreaseChangePeriod\n );\n }\n\n /// @notice Updates the values of DKG parameters.\n /// @dev Can be called only by the contract guvnor, which should be the\n /// wallet registry governance contract. The caller is responsible for\n /// validating parameters.\n /// @param _seedTimeout New seed timeout.\n /// @param _resultChallengePeriodLength New DKG result challenge period\n /// length.\n /// @param _resultChallengeExtraGas New extra gas value required to be left\n /// at the end of the DKG result challenge transaction.\n /// @param _resultSubmissionTimeout New DKG result submission timeout.\n /// @param _submitterPrecedencePeriodLength New submitter precedence period\n /// length.\n function updateDkgParameters(\n uint256 _seedTimeout,\n uint256 _resultChallengePeriodLength,\n uint256 _resultChallengeExtraGas,\n uint256 _resultSubmissionTimeout,\n uint256 _submitterPrecedencePeriodLength\n ) external onlyGovernance {\n dkg.setSeedTimeout(_seedTimeout);\n dkg.setResultChallengePeriodLength(_resultChallengePeriodLength);\n dkg.setResultChallengeExtraGas(_resultChallengeExtraGas);\n dkg.setResultSubmissionTimeout(_resultSubmissionTimeout);\n dkg.setSubmitterPrecedencePeriodLength(\n _submitterPrecedencePeriodLength\n );\n\n // slither-disable-next-line reentrancy-events\n emit DkgParametersUpdated(\n _seedTimeout,\n _resultChallengePeriodLength,\n _resultChallengeExtraGas,\n _resultSubmissionTimeout,\n _submitterPrecedencePeriodLength\n );\n }\n\n /// @notice Updates the values of reward parameters.\n /// @dev Can be called only by the contract guvnor, which should be the\n /// wallet registry governance contract. The caller is responsible for\n /// validating parameters.\n /// @param maliciousDkgResultNotificationRewardMultiplier New value of the\n /// DKG malicious result notification reward multiplier.\n /// @param sortitionPoolRewardsBanDuration New sortition pool rewards\n /// ban duration in seconds.\n function updateRewardParameters(\n uint256 maliciousDkgResultNotificationRewardMultiplier,\n uint256 sortitionPoolRewardsBanDuration\n ) external onlyGovernance {\n _maliciousDkgResultNotificationRewardMultiplier = maliciousDkgResultNotificationRewardMultiplier;\n _sortitionPoolRewardsBanDuration = sortitionPoolRewardsBanDuration;\n emit RewardParametersUpdated(\n maliciousDkgResultNotificationRewardMultiplier,\n sortitionPoolRewardsBanDuration\n );\n }\n\n /// @notice Updates the values of slashing parameters.\n /// @dev Can be called only by the contract guvnor, which should be the\n /// wallet registry governance contract. The caller is responsible for\n /// validating parameters.\n /// @param maliciousDkgResultSlashingAmount New malicious DKG result\n /// slashing amount.\n function updateSlashingParameters(uint96 maliciousDkgResultSlashingAmount)\n external\n onlyGovernance\n {\n _maliciousDkgResultSlashingAmount = maliciousDkgResultSlashingAmount;\n emit SlashingParametersUpdated(maliciousDkgResultSlashingAmount);\n }\n\n /// @notice Updates the values of gas-related parameters.\n /// @dev Can be called only by the contract guvnor, which should be the\n /// wallet registry governance contract. The caller is responsible for\n /// validating parameters.\n /// @param dkgResultSubmissionGas New DKG result submission gas.\n /// @param dkgResultApprovalGasOffset New DKG result approval gas offset.\n /// @param notifyOperatorInactivityGasOffset New operator inactivity\n /// notification gas offset.\n /// @param notifySeedTimeoutGasOffset New seed for DKG delivery timeout\n /// notification gas offset.\n /// @param notifyDkgTimeoutNegativeGasOffset New DKG timeout notification gas\n /// offset.\n function updateGasParameters(\n uint256 dkgResultSubmissionGas,\n uint256 dkgResultApprovalGasOffset,\n uint256 notifyOperatorInactivityGasOffset,\n uint256 notifySeedTimeoutGasOffset,\n uint256 notifyDkgTimeoutNegativeGasOffset\n ) external onlyGovernance {\n _dkgResultSubmissionGas = dkgResultSubmissionGas;\n _dkgResultApprovalGasOffset = dkgResultApprovalGasOffset;\n _notifyOperatorInactivityGasOffset = notifyOperatorInactivityGasOffset;\n _notifySeedTimeoutGasOffset = notifySeedTimeoutGasOffset;\n _notifyDkgTimeoutNegativeGasOffset = notifyDkgTimeoutNegativeGasOffset;\n\n emit GasParametersUpdated(\n dkgResultSubmissionGas,\n dkgResultApprovalGasOffset,\n notifyOperatorInactivityGasOffset,\n _notifySeedTimeoutGasOffset,\n _notifyDkgTimeoutNegativeGasOffset\n );\n }\n\n /// @notice Requests a new wallet creation.\n /// @dev Can be called only by the owner of wallets.\n /// It locks the DKG and request a new relay entry. It expects\n /// that the DKG process will be started once a new relay entry\n /// gets generated.\n function requestNewWallet() external onlyWalletOwner {\n dkg.lockState();\n\n randomBeacon.requestRelayEntry(this);\n }\n\n /// @notice Closes an existing wallet. Reverts if wallet with the given ID\n /// does not exist or if it has already been closed.\n /// @param walletID ID of the wallet.\n /// @dev Only a Wallet Owner can call this function.\n function closeWallet(bytes32 walletID) external onlyWalletOwner {\n wallets.deleteWallet(walletID);\n emit WalletClosed(walletID);\n }\n\n /// @notice A callback that is executed once a new relay entry gets\n /// generated. It starts the DKG process.\n /// @dev Can be called only by the random beacon contract.\n /// @param relayEntry Relay entry.\n function __beaconCallback(uint256 relayEntry, uint256) external {\n require(\n msg.sender == address(randomBeacon),\n \"Caller is not the Random Beacon\"\n );\n\n dkg.start(relayEntry);\n }\n\n /// @notice Submits result of DKG protocol.\n /// The DKG result consists of result submitting member index,\n /// calculated group public key, bytes array of misbehaved members,\n /// concatenation of signatures from group members, indices of members\n /// corresponding to each signature and the list of group members.\n /// The result is registered optimistically and waits for an approval.\n /// The result can be challenged when it is believed to be incorrect.\n /// The challenge verifies the registered result i.a. it checks if members\n /// list corresponds to the expected set of members determined\n /// by the sortition pool.\n /// @dev The message to be signed by each member is keccak256 hash of the\n /// chain ID, calculated group public key, misbehaved members indices\n /// and DKG start block. The calculated hash should be prefixed with\n /// `\\x19Ethereum signed message:\\n` before signing, so the message to\n /// sign is:\n /// `\\x19Ethereum signed message:\\n${keccak256(chainID,groupPubKey,misbehavedIndices,startBlock)}`\n /// @param dkgResult DKG result.\n function submitDkgResult(DKG.Result calldata dkgResult) external {\n wallets.validatePublicKey(dkgResult.groupPubKey);\n dkg.submitResult(dkgResult);\n }\n\n /// @notice Approves DKG result. Can be called when the challenge period for\n /// the submitted result is finished. Considers the submitted result\n /// as valid, bans misbehaved group members from the sortition pool\n /// rewards, and completes the group creation by activating the\n /// candidate group. For the first `resultSubmissionTimeout` blocks\n /// after the end of the challenge period can be called only by the\n /// DKG result submitter. After that time, can be called by anyone.\n /// A new wallet based on the DKG result details.\n /// @param dkgResult Result to approve. Must match the submitted result\n /// stored during `submitDkgResult`.\n function approveDkgResult(DKG.Result calldata dkgResult) external {\n uint256 gasStart = gasleft();\n uint32[] memory misbehavedMembers = dkg.approveResult(dkgResult);\n\n (bytes32 walletID, bytes32 publicKeyX, bytes32 publicKeyY) = wallets\n .addWallet(dkgResult.membersHash, dkgResult.groupPubKey);\n\n emit WalletCreated(walletID, keccak256(abi.encode(dkgResult)));\n\n if (misbehavedMembers.length > 0) {\n sortitionPool.setRewardIneligibility(\n misbehavedMembers,\n // solhint-disable-next-line not-rely-on-time\n block.timestamp + _sortitionPoolRewardsBanDuration\n );\n }\n\n walletOwner.__ecdsaWalletCreatedCallback(\n walletID,\n publicKeyX,\n publicKeyY\n );\n\n dkg.complete();\n\n // Refund msg.sender's ETH for DKG result submission and result approval\n reimbursementPool.refund(\n _dkgResultSubmissionGas +\n (gasStart - gasleft()) +\n _dkgResultApprovalGasOffset,\n msg.sender\n );\n }\n\n /// @notice Notifies about seed for DKG delivery timeout. It is expected\n /// that a seed is delivered by the Random Beacon as a relay entry in a\n /// callback function.\n function notifySeedTimeout() external {\n uint256 gasStart = gasleft();\n\n dkg.notifySeedTimeout();\n\n reimbursementPool.refund(\n (gasStart - gasleft()) + _notifySeedTimeoutGasOffset,\n msg.sender\n );\n }\n\n /// @notice Notifies about DKG timeout.\n function notifyDkgTimeout() external {\n uint256 gasStart = gasleft();\n\n dkg.notifyDkgTimeout();\n\n // Note that the offset is subtracted as it is expected that the cleanup\n // performed on DKG timeout notification removes data from the storage\n // which is recovering gas for the transaction.\n reimbursementPool.refund(\n (gasStart - gasleft()) - _notifyDkgTimeoutNegativeGasOffset,\n msg.sender\n );\n }\n\n /// @notice Challenges DKG result. If the submitted result is proved to be\n /// invalid it reverts the DKG back to the result submission phase.\n /// @param dkgResult Result to challenge. Must match the submitted result\n /// stored during `submitDkgResult`.\n /// @dev Due to EIP-150 1/64 of the gas is not forwarded to the call, and\n /// will be kept to execute the remaining operations in the function\n /// after the call inside the try-catch. To eliminate a class of\n /// attacks related to the gas limit manipulation, this function\n /// requires an extra amount of gas to be left at the end of the\n /// execution.\n function challengeDkgResult(DKG.Result calldata dkgResult) external {\n // solhint-disable-next-line avoid-tx-origin\n require(msg.sender == tx.origin, \"Not EOA\");\n\n (\n bytes32 maliciousDkgResultHash,\n uint32 maliciousDkgResultSubmitterId\n ) = dkg.challengeResult(dkgResult);\n\n address maliciousDkgResultSubmitterAddress = sortitionPool\n .getIDOperator(maliciousDkgResultSubmitterId);\n\n address[] memory operatorWrapper = new address[](1);\n operatorWrapper[0] = operatorToStakingProvider(\n maliciousDkgResultSubmitterAddress\n );\n\n try\n staking.seize(\n _maliciousDkgResultSlashingAmount,\n _maliciousDkgResultNotificationRewardMultiplier,\n msg.sender,\n operatorWrapper\n )\n {\n // slither-disable-next-line reentrancy-events\n emit DkgMaliciousResultSlashed(\n maliciousDkgResultHash,\n _maliciousDkgResultSlashingAmount,\n maliciousDkgResultSubmitterAddress\n );\n } catch {\n // Should never happen but we want to ensure a non-critical path\n // failure from an external contract does not stop the challenge\n // to complete.\n emit DkgMaliciousResultSlashingFailed(\n maliciousDkgResultHash,\n _maliciousDkgResultSlashingAmount,\n maliciousDkgResultSubmitterAddress\n );\n }\n\n // Due to EIP-150, 1/64 of the gas is not forwarded to the call, and\n // will be kept to execute the remaining operations in the function\n // after the call inside the try-catch.\n //\n // To ensure there is no way for the caller to manipulate gas limit in\n // such a way that the call inside try-catch fails with out-of-gas and\n // the rest of the function is executed with the remaining 1/64 of gas,\n // we require an extra gas amount to be left at the end of the call to\n // `challengeDkgResult`.\n dkg.requireChallengeExtraGas();\n }\n\n /// @notice Notifies about operators who are inactive. Using this function,\n /// a majority of the wallet signing group can decide about\n /// punishing specific group members who constantly fail doing their\n /// job. If the provided claim is proved to be valid and signed by\n /// sufficient number of group members, operators of members deemed\n /// as inactive are banned from sortition pool rewards for the\n /// duration specified by `sortitionPoolRewardsBanDuration` parameter.\n /// The function allows to signal about single operators being\n /// inactive as well as to signal wallet-wide heartbeat failures\n /// that are propagated to the wallet owner who should begin the\n /// procedure of moving responsibilities to another wallet given\n /// that the wallet who failed the heartbeat may soon be not able to\n /// function and provide new signatures.\n /// The sender of the claim must be one of the claim signers. This\n /// function can be called only for registered wallets\n /// @param claim Operator inactivity claim.\n /// @param nonce Current inactivity claim nonce for the given wallet signing\n /// group. Must be the same as the stored one.\n /// @param groupMembers Identifiers of the wallet signing group members.\n function notifyOperatorInactivity(\n Inactivity.Claim calldata claim,\n uint256 nonce,\n uint32[] calldata groupMembers\n ) external {\n uint256 gasStart = gasleft();\n\n bytes32 walletID = claim.walletID;\n\n require(nonce == inactivityClaimNonce[walletID], \"Invalid nonce\");\n\n (bytes32 pubKeyX, bytes32 pubKeyY) = wallets\n .getWalletPublicKeyCoordinates(walletID);\n bytes32 memberIdsHash = wallets.getWalletMembersIdsHash(walletID);\n\n require(\n memberIdsHash == keccak256(abi.encode(groupMembers)),\n \"Invalid group members\"\n );\n\n uint32[] memory ineligibleOperators = Inactivity.verifyClaim(\n sortitionPool,\n claim,\n bytes.concat(pubKeyX, pubKeyY),\n nonce,\n groupMembers\n );\n\n inactivityClaimNonce[walletID]++;\n\n emit InactivityClaimed(walletID, nonce, msg.sender);\n\n sortitionPool.setRewardIneligibility(\n ineligibleOperators,\n // solhint-disable-next-line not-rely-on-time\n block.timestamp + _sortitionPoolRewardsBanDuration\n );\n\n if (claim.heartbeatFailed) {\n walletOwner.__ecdsaWalletHeartbeatFailedCallback(\n walletID,\n pubKeyX,\n pubKeyY\n );\n }\n\n reimbursementPool.refund(\n (gasStart - gasleft()) + _notifyOperatorInactivityGasOffset,\n msg.sender\n );\n }\n\n /// @notice Allows the wallet owner to add all signing group members of the\n /// wallet with the given ID to the slashing queue of the staking .\n /// contract. The notifier will receive reward per each group member\n /// from the staking contract notifiers treasury. The reward is\n /// scaled by the `rewardMultiplier` provided as a parameter.\n /// @param amount Amount of tokens to seize from each signing group member.\n /// @param rewardMultiplier Fraction of the staking contract notifiers\n /// reward the notifier should receive; should be between [0, 100].\n /// @param notifier Address of the misbehavior notifier.\n /// @param walletID ID of the wallet.\n /// @param walletMembersIDs Identifiers of the wallet signing group members.\n /// @dev Requirements:\n /// - The expression `keccak256(abi.encode(walletMembersIDs))` must\n /// be exactly the same as the hash stored under `membersIdsHash`\n /// for the given `walletID`. Those IDs are not directly stored\n /// in the contract for gas efficiency purposes but they can be\n /// read from appropriate `DkgResultSubmitted` and `DkgResultApproved`\n /// events.\n /// - `rewardMultiplier` must be between [0, 100].\n /// - This function does revert if staking contract call reverts.\n /// The calling code needs to handle the potential revert.\n function seize(\n uint96 amount,\n uint256 rewardMultiplier,\n address notifier,\n bytes32 walletID,\n uint32[] calldata walletMembersIDs\n ) external onlyWalletOwner {\n bytes32 memberIdsHash = wallets.getWalletMembersIdsHash(walletID);\n require(\n memberIdsHash == keccak256(abi.encode(walletMembersIDs)),\n \"Invalid wallet members identifiers\"\n );\n\n address[] memory groupMembersAddresses = sortitionPool.getIDOperators(\n walletMembersIDs\n );\n address[] memory stakingProvidersAddresses = new address[](\n walletMembersIDs.length\n );\n for (uint256 i = 0; i < groupMembersAddresses.length; i++) {\n stakingProvidersAddresses[i] = operatorToStakingProvider(\n groupMembersAddresses[i]\n );\n }\n\n staking.seize(\n amount,\n rewardMultiplier,\n notifier,\n stakingProvidersAddresses\n );\n }\n\n /// @notice Checks if DKG result is valid for the current DKG.\n /// @param result DKG result.\n /// @return True if the result is valid. If the result is invalid it returns\n /// false and an error message.\n function isDkgResultValid(DKG.Result calldata result)\n external\n view\n returns (bool, string memory)\n {\n return dkg.isResultValid(result);\n }\n\n /// @notice Check current wallet creation state.\n function getWalletCreationState() external view returns (DKG.State) {\n return dkg.currentState();\n }\n\n /// @notice Checks whether the given operator is a member of the given\n /// wallet signing group.\n /// @param walletID ID of the wallet.\n /// @param walletMembersIDs Identifiers of the wallet signing group members.\n /// @param operator Address of the checked operator.\n /// @param walletMemberIndex Position of the operator in the wallet signing\n /// group members list.\n /// @return True - if the operator is a member of the given wallet signing\n /// group. False - otherwise.\n /// @dev Requirements:\n /// - The `operator` parameter must be an actual sortition pool operator.\n /// - The expression `keccak256(abi.encode(walletMembersIDs))` must\n /// be exactly the same as the hash stored under `membersIdsHash`\n /// for the given `walletID`. Those IDs are not directly stored\n /// in the contract for gas efficiency purposes but they can be\n /// read from appropriate `DkgResultSubmitted` and `DkgResultApproved`\n /// events.\n /// - The `walletMemberIndex` must be in range [1, walletMembersIDs.length]\n function isWalletMember(\n bytes32 walletID,\n uint32[] calldata walletMembersIDs,\n address operator,\n uint256 walletMemberIndex\n ) external view returns (bool) {\n uint32 operatorID = sortitionPool.getOperatorID(operator);\n\n require(operatorID != 0, \"Not a sortition pool operator\");\n\n bytes32 memberIdsHash = wallets.getWalletMembersIdsHash(walletID);\n\n require(\n memberIdsHash == keccak256(abi.encode(walletMembersIDs)),\n \"Invalid wallet members identifiers\"\n );\n\n require(\n 1 <= walletMemberIndex &&\n walletMemberIndex <= walletMembersIDs.length,\n \"Wallet member index is out of range\"\n );\n\n return walletMembersIDs[walletMemberIndex - 1] == operatorID;\n }\n\n /// @notice Checks if awaiting seed timed out.\n /// @return True if awaiting seed timed out, false otherwise.\n function hasSeedTimedOut() external view returns (bool) {\n return dkg.hasSeedTimedOut();\n }\n\n /// @notice Checks if DKG timed out. The DKG timeout period includes time required\n /// for off-chain protocol execution and time for the result publication\n /// for all group members. After this time result cannot be submitted\n /// and DKG can be notified about the timeout.\n /// @return True if DKG timed out, false otherwise.\n function hasDkgTimedOut() external view returns (bool) {\n return dkg.hasDkgTimedOut();\n }\n\n function getWallet(bytes32 walletID)\n external\n view\n returns (Wallets.Wallet memory)\n {\n return wallets.registry[walletID];\n }\n\n /// @notice Gets public key of a wallet with a given wallet ID.\n /// The public key is returned in an uncompressed format as a 64-byte\n /// concatenation of X and Y coordinates.\n /// @param walletID ID of the wallet.\n /// @return Uncompressed public key of the wallet.\n function getWalletPublicKey(bytes32 walletID)\n external\n view\n returns (bytes memory)\n {\n return wallets.getWalletPublicKey(walletID);\n }\n\n /// @notice Checks if a wallet with the given ID is registered.\n /// @param walletID Wallet's ID.\n /// @return True if wallet is registered, false otherwise.\n function isWalletRegistered(bytes32 walletID) external view returns (bool) {\n return wallets.isWalletRegistered(walletID);\n }\n\n /// @notice The minimum authorization amount required so that operator can\n /// participate in ECDSA Wallet operations.\n function minimumAuthorization() external view returns (uint96) {\n return authorization.parameters.minimumAuthorization;\n }\n\n /// @notice Returns the current value of the staking provider's eligible\n /// stake. Eligible stake is defined as the currently authorized\n /// stake minus the pending authorization decrease. Eligible stake\n /// is what is used for operator's weight in the sortition pool.\n /// If the authorized stake minus the pending authorization decrease\n /// is below the minimum authorization, eligible stake is 0.\n function eligibleStake(address stakingProvider)\n external\n view\n returns (uint96)\n {\n return authorization.eligibleStake(staking, stakingProvider);\n }\n\n /// @notice Returns the amount of rewards available for withdrawal for the\n /// given staking provider. Reverts if staking provider has not\n /// registered the operator address.\n function availableRewards(address stakingProvider)\n external\n view\n returns (uint96)\n {\n address operator = stakingProviderToOperator(stakingProvider);\n require(operator != address(0), \"Unknown operator\");\n return sortitionPool.getAvailableRewards(operator);\n }\n\n /// @notice Returns the amount of stake that is pending authorization\n /// decrease for the given staking provider. If no authorization\n /// decrease has been requested, returns zero.\n function pendingAuthorizationDecrease(address stakingProvider)\n external\n view\n returns (uint96)\n {\n return authorization.pendingAuthorizationDecrease(stakingProvider);\n }\n\n /// @notice Returns the remaining time in seconds that needs to pass before\n /// the requested authorization decrease can be approved.\n /// If the sortition pool state was not updated yet by the operator\n /// after requesting the authorization decrease, returns\n /// `type(uint64).max`.\n function remainingAuthorizationDecreaseDelay(address stakingProvider)\n external\n view\n returns (uint64)\n {\n return\n authorization.remainingAuthorizationDecreaseDelay(stakingProvider);\n }\n\n /// @notice Returns operator registered for the given staking provider.\n function stakingProviderToOperator(address stakingProvider)\n public\n view\n returns (address)\n {\n return authorization.stakingProviderToOperator[stakingProvider];\n }\n\n /// @notice Returns staking provider of the given operator.\n function operatorToStakingProvider(address operator)\n public\n view\n returns (address)\n {\n return authorization.operatorToStakingProvider[operator];\n }\n\n /// @notice Checks if the operator's authorized stake is in sync with\n /// operator's weight in the sortition pool.\n /// If the operator is not in the sortition pool and their\n /// authorized stake is non-zero, function returns false.\n function isOperatorUpToDate(address operator) external view returns (bool) {\n return\n authorization.isOperatorUpToDate(staking, sortitionPool, operator);\n }\n\n /// @notice Returns true if the given operator is in the sortition pool.\n /// Otherwise, returns false.\n function isOperatorInPool(address operator) external view returns (bool) {\n return sortitionPool.isOperatorInPool(operator);\n }\n\n /// @notice Selects a new group of operators. Can only be called when DKG\n /// is in progress and the pool is locked.\n /// At least one operator has to be registered in the pool,\n /// otherwise the function fails reverting the transaction.\n /// @return IDs of selected group members.\n function selectGroup() external view returns (uint32[] memory) {\n return sortitionPool.selectGroup(DKG.groupSize, bytes32(dkg.seed));\n }\n\n /// @notice Retrieves dkg parameters that were set in DKG library.\n function dkgParameters() external view returns (DKG.Parameters memory) {\n return dkg.parameters;\n }\n\n /// @notice Returns authorization-related parameters.\n /// @dev The minimum authorization is also returned by `minimumAuthorization()`\n /// function, as a requirement of `IApplication` interface.\n /// @return minimumAuthorization The minimum authorization amount required\n /// so that operator can participate in the random beacon. This\n /// amount is required to execute slashing for providing a malicious\n /// DKG result or when a relay entry times out.\n /// @return authorizationDecreaseDelay Delay in seconds that needs to pass\n /// between the time authorization decrease is requested and the\n /// time that request gets approved. Protects against free-riders\n /// earning rewards and not being active in the network.\n /// @return authorizationDecreaseChangePeriod Authorization decrease change\n /// period in seconds. It is the time, before authorization decrease\n /// delay end, during which the pending authorization decrease\n /// request can be overwritten.\n /// If set to 0, pending authorization decrease request can not be\n /// overwritten until the entire `authorizationDecreaseDelay` ends.\n /// If set to value equal `authorizationDecreaseDelay`, request can\n /// always be overwritten.\n function authorizationParameters()\n external\n view\n returns (\n uint96 minimumAuthorization,\n uint64 authorizationDecreaseDelay,\n uint64 authorizationDecreaseChangePeriod\n )\n {\n return (\n authorization.parameters.minimumAuthorization,\n authorization.parameters.authorizationDecreaseDelay,\n authorization.parameters.authorizationDecreaseChangePeriod\n );\n }\n\n /// @notice Retrieves reward-related parameters.\n /// @return maliciousDkgResultNotificationRewardMultiplier Percentage of the\n /// staking contract malicious behavior notification reward which\n /// will be transferred to the notifier reporting about a malicious\n /// DKG result. Notifiers are rewarded from a notifiers treasury\n /// pool. For example, if notification reward is 1000 and the value\n /// of the multiplier is 5, the notifier will receive:\n /// 5% of 1000 = 50 per each operator affected.\n /// @return sortitionPoolRewardsBanDuration Duration of the sortition pool\n /// rewards ban imposed on operators who missed their turn for DKG\n /// result submission or who failed a heartbeat.\n function rewardParameters()\n external\n view\n returns (\n uint256 maliciousDkgResultNotificationRewardMultiplier,\n uint256 sortitionPoolRewardsBanDuration\n )\n {\n return (\n _maliciousDkgResultNotificationRewardMultiplier,\n _sortitionPoolRewardsBanDuration\n );\n }\n\n /// @notice Retrieves slashing-related parameters.\n /// @return maliciousDkgResultSlashingAmount Slashing amount for submitting\n /// a malicious DKG result. Every DKG result submitted can be\n /// challenged for the time of `dkg.resultChallengePeriodLength`.\n /// If the DKG result submitted is challenged and proven to be\n /// malicious, the operator who submitted the malicious result is\n /// slashed for `_maliciousDkgResultSlashingAmount`.\n function slashingParameters()\n external\n view\n returns (uint96 maliciousDkgResultSlashingAmount)\n {\n return _maliciousDkgResultSlashingAmount;\n }\n\n /// @notice Retrieves gas-related parameters.\n /// @return dkgResultSubmissionGas Calculated max gas cost for submitting\n /// a DKG result. This will be refunded as part of the DKG approval\n /// process. It is in the submitter's interest to not skip his\n /// priority turn on the approval, otherwise the refund of the DKG\n /// submission will be refunded to another group member that will\n /// call the DKG approve function.\n /// @return dkgResultApprovalGasOffset Gas that is meant to balance the DKG\n /// result approval's overall cost. It can be updated by the\n /// governance based on the current market conditions.\n /// @return notifyOperatorInactivityGasOffset Gas that is meant to balance\n /// the notification of an operator inactivity. It can be updated by\n /// the governance based on the current market conditions.\n /// @return notifySeedTimeoutGasOffset Gas that is meant to balance the\n /// notification of a seed for DKG delivery timeout. It can be updated\n /// by the governance based on the current market conditions.\n /// @return notifyDkgTimeoutNegativeGasOffset Gas that is meant to balance\n /// the notification of a DKG protocol execution timeout. It can be\n /// updated by the governance based on the current market conditions.\n function gasParameters()\n external\n view\n returns (\n uint256 dkgResultSubmissionGas,\n uint256 dkgResultApprovalGasOffset,\n uint256 notifyOperatorInactivityGasOffset,\n uint256 notifySeedTimeoutGasOffset,\n uint256 notifyDkgTimeoutNegativeGasOffset\n )\n {\n return (\n _dkgResultSubmissionGas,\n _dkgResultApprovalGasOffset,\n _notifyOperatorInactivityGasOffset,\n _notifySeedTimeoutGasOffset,\n _notifyDkgTimeoutNegativeGasOffset\n );\n }\n}\n" + }, + "@keep-network/random-beacon/contracts/api/IRandomBeacon.sol": { + "content": "// SPDX-License-Identifier: GPL-3.0-only\n//\n// ▓▓▌ ▓▓ ▐▓▓ ▓▓▓▓▓▓▓▓▓▓▌▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▄\n// ▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▌▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓\n// ▓▓▓▓▓▓ ▓▓▓▓▓▓▓▀ ▐▓▓▓▓▓▓ ▐▓▓▓▓▓ ▓▓▓▓▓▓ ▓▓▓▓▓ ▐▓▓▓▓▓▌ ▐▓▓▓▓▓▓\n// ▓▓▓▓▓▓▄▄▓▓▓▓▓▓▓▀ ▐▓▓▓▓▓▓▄▄▄▄ ▓▓▓▓▓▓▄▄▄▄ ▐▓▓▓▓▓▌ ▐▓▓▓▓▓▓\n// ▓▓▓▓▓▓▓▓▓▓▓▓▓▀ ▐▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓\n// ▓▓▓▓▓▓▀▀▓▓▓▓▓▓▄ ▐▓▓▓▓▓▓▀▀▀▀ ▓▓▓▓▓▓▀▀▀▀ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▀\n// ▓▓▓▓▓▓ ▀▓▓▓▓▓▓▄ ▐▓▓▓▓▓▓ ▓▓▓▓▓ ▓▓▓▓▓▓ ▓▓▓▓▓ ▐▓▓▓▓▓▌\n// ▓▓▓▓▓▓▓▓▓▓ █▓▓▓▓▓▓▓▓▓ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓\n// ▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓\n//\n// Trust math, not hardware.\n\npragma solidity 0.8.17;\n\nimport \"./IRandomBeaconConsumer.sol\";\n\n/// @title Random Beacon interface\ninterface IRandomBeacon {\n /// @notice Creates a request to generate a new relay entry. Requires a\n /// request fee denominated in T token.\n /// @param callbackContract Beacon consumer callback contract.\n function requestRelayEntry(IRandomBeaconConsumer callbackContract) external;\n}\n" + }, + "@keep-network/random-beacon/contracts/api/IRandomBeaconConsumer.sol": { + "content": "// SPDX-License-Identifier: GPL-3.0-only\n//\n// ▓▓▌ ▓▓ ▐▓▓ ▓▓▓▓▓▓▓▓▓▓▌▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▄\n// ▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▌▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓\n// ▓▓▓▓▓▓ ▓▓▓▓▓▓▓▀ ▐▓▓▓▓▓▓ ▐▓▓▓▓▓ ▓▓▓▓▓▓ ▓▓▓▓▓ ▐▓▓▓▓▓▌ ▐▓▓▓▓▓▓\n// ▓▓▓▓▓▓▄▄▓▓▓▓▓▓▓▀ ▐▓▓▓▓▓▓▄▄▄▄ ▓▓▓▓▓▓▄▄▄▄ ▐▓▓▓▓▓▌ ▐▓▓▓▓▓▓\n// ▓▓▓▓▓▓▓▓▓▓▓▓▓▀ ▐▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓\n// ▓▓▓▓▓▓▀▀▓▓▓▓▓▓▄ ▐▓▓▓▓▓▓▀▀▀▀ ▓▓▓▓▓▓▀▀▀▀ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▀\n// ▓▓▓▓▓▓ ▀▓▓▓▓▓▓▄ ▐▓▓▓▓▓▓ ▓▓▓▓▓ ▓▓▓▓▓▓ ▓▓▓▓▓ ▐▓▓▓▓▓▌\n// ▓▓▓▓▓▓▓▓▓▓ █▓▓▓▓▓▓▓▓▓ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓\n// ▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓\n//\n// Trust math, not hardware.\n\npragma solidity 0.8.17;\n\ninterface IRandomBeaconConsumer {\n /// @notice Receives relay entry produced by Keep Random Beacon. This function\n /// should be called only by Keep Random Beacon.\n ///\n /// @param relayEntry Relay entry (random number) produced by Keep Random\n /// Beacon.\n /// @param blockNumber Block number at which the relay entry was submitted\n /// to the chain.\n function __beaconCallback(uint256 relayEntry, uint256 blockNumber) external;\n}\n" + }, + "@keep-network/random-beacon/contracts/Governable.sol": { + "content": "// SPDX-License-Identifier: GPL-3.0-only\n//\n// ▓▓▌ ▓▓ ▐▓▓ ▓▓▓▓▓▓▓▓▓▓▌▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▄\n// ▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▌▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓\n// ▓▓▓▓▓▓ ▓▓▓▓▓▓▓▀ ▐▓▓▓▓▓▓ ▐▓▓▓▓▓ ▓▓▓▓▓▓ ▓▓▓▓▓ ▐▓▓▓▓▓▌ ▐▓▓▓▓▓▓\n// ▓▓▓▓▓▓▄▄▓▓▓▓▓▓▓▀ ▐▓▓▓▓▓▓▄▄▄▄ ▓▓▓▓▓▓▄▄▄▄ ▐▓▓▓▓▓▌ ▐▓▓▓▓▓▓\n// ▓▓▓▓▓▓▓▓▓▓▓▓▓▀ ▐▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓\n// ▓▓▓▓▓▓▀▀▓▓▓▓▓▓▄ ▐▓▓▓▓▓▓▀▀▀▀ ▓▓▓▓▓▓▀▀▀▀ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▀\n// ▓▓▓▓▓▓ ▀▓▓▓▓▓▓▄ ▐▓▓▓▓▓▓ ▓▓▓▓▓ ▓▓▓▓▓▓ ▓▓▓▓▓ ▐▓▓▓▓▓▌\n// ▓▓▓▓▓▓▓▓▓▓ █▓▓▓▓▓▓▓▓▓ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓\n// ▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓\n//\n// Trust math, not hardware.\n\npragma solidity 0.8.17;\n\n/// @notice Governable contract.\n/// @dev A constructor is not defined, which makes the contract compatible with\n/// upgradable proxies. This requires calling explicitly `_transferGovernance`\n/// function in a child contract.\nabstract contract Governable {\n // Governance of the contract\n // The variable should be initialized by the implementing contract.\n // slither-disable-next-line uninitialized-state\n address public governance;\n\n // Reserved storage space in case we need to add more variables,\n // since there are upgradeable contracts that inherit from this one.\n // See https://docs.openzeppelin.com/contracts/4.x/upgradeable#storage_gaps\n // slither-disable-next-line unused-state\n uint256[49] private __gap;\n\n event GovernanceTransferred(address oldGovernance, address newGovernance);\n\n modifier onlyGovernance() virtual {\n require(governance == msg.sender, \"Caller is not the governance\");\n _;\n }\n\n /// @notice Transfers governance of the contract to `newGovernance`.\n function transferGovernance(address newGovernance)\n external\n virtual\n onlyGovernance\n {\n require(\n newGovernance != address(0),\n \"New governance is the zero address\"\n );\n _transferGovernance(newGovernance);\n }\n\n function _transferGovernance(address newGovernance) internal virtual {\n address oldGovernance = governance;\n governance = newGovernance;\n emit GovernanceTransferred(oldGovernance, newGovernance);\n }\n}\n" + }, + "@keep-network/random-beacon/contracts/libraries/BytesLib.sol": { + "content": "// SPDX-License-Identifier: GPL-3.0-only\n//\n// ▓▓▌ ▓▓ ▐▓▓ ▓▓▓▓▓▓▓▓▓▓▌▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▄\n// ▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▌▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓\n// ▓▓▓▓▓▓ ▓▓▓▓▓▓▓▀ ▐▓▓▓▓▓▓ ▐▓▓▓▓▓ ▓▓▓▓▓▓ ▓▓▓▓▓ ▐▓▓▓▓▓▌ ▐▓▓▓▓▓▓\n// ▓▓▓▓▓▓▄▄▓▓▓▓▓▓▓▀ ▐▓▓▓▓▓▓▄▄▄▄ ▓▓▓▓▓▓▄▄▄▄ ▐▓▓▓▓▓▌ ▐▓▓▓▓▓▓\n// ▓▓▓▓▓▓▓▓▓▓▓▓▓▀ ▐▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓\n// ▓▓▓▓▓▓▀▀▓▓▓▓▓▓▄ ▐▓▓▓▓▓▓▀▀▀▀ ▓▓▓▓▓▓▀▀▀▀ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▀\n// ▓▓▓▓▓▓ ▀▓▓▓▓▓▓▄ ▐▓▓▓▓▓▓ ▓▓▓▓▓ ▓▓▓▓▓▓ ▓▓▓▓▓ ▐▓▓▓▓▓▌\n// ▓▓▓▓▓▓▓▓▓▓ █▓▓▓▓▓▓▓▓▓ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓\n// ▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓\n//\n//\n\npragma solidity 0.8.17;\n\n/*\nVersion pulled from keep-core v1:\nhttps://github.com/keep-network/keep-core/blob/f297202db00c027978ad8e7103a356503de5773c/solidity-v1/contracts/utils/BytesLib.sol\n\nTo compile it with solidity 0.8 `_preBytes_slot` was replaced with `_preBytes.slot`.\n*/\n\n/*\nhttps://github.com/GNSPS/solidity-bytes-utils/\nThis is free and unencumbered software released into the public domain.\nAnyone is free to copy, modify, publish, use, compile, sell, or\ndistribute this software, either in source code form or as a compiled\nbinary, for any purpose, commercial or non-commercial, and by any\nmeans.\nIn jurisdictions that recognize copyright laws, the author or authors\nof this software dedicate any and all copyright interest in the\nsoftware to the public domain. We make this dedication for the benefit\nof the public at large and to the detriment of our heirs and\nsuccessors. We intend this dedication to be an overt act of\nrelinquishment in perpetuity of all present and future rights to this\nsoftware under copyright law.\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND,\nEXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF\nMERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.\nIN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR\nOTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,\nARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR\nOTHER DEALINGS IN THE SOFTWARE.\nFor more information, please refer to \n*/\n\n/** @title BytesLib **/\n/** @author https://github.com/GNSPS **/\n\nlibrary BytesLib {\n function concatStorage(bytes storage _preBytes, bytes memory _postBytes)\n internal\n {\n assembly {\n // Read the first 32 bytes of _preBytes storage, which is the length\n // of the array. (We don't need to use the offset into the slot\n // because arrays use the entire slot.)\n let fslot := sload(_preBytes.slot)\n // Arrays of 31 bytes or less have an even value in their slot,\n // while longer arrays have an odd value. The actual length is\n // the slot divided by two for odd values, and the lowest order\n // byte divided by two for even values.\n // If the slot is even, bitwise and the slot with 255 and divide by\n // two to get the length. If the slot is odd, bitwise and the slot\n // with -1 and divide by two.\n let slength := div(\n and(fslot, sub(mul(0x100, iszero(and(fslot, 1))), 1)),\n 2\n )\n let mlength := mload(_postBytes)\n let newlength := add(slength, mlength)\n // slength can contain both the length and contents of the array\n // if length < 32 bytes so let's prepare for that\n // v. http://solidity.readthedocs.io/en/latest/miscellaneous.html#layout-of-state-variables-in-storage\n switch add(lt(slength, 32), lt(newlength, 32))\n case 2 {\n // Since the new array still fits in the slot, we just need to\n // update the contents of the slot.\n // uint256(bytes_storage) = uint256(bytes_storage) + uint256(bytes_memory) + new_length\n sstore(\n _preBytes.slot,\n // all the modifications to the slot are inside this\n // next block\n add(\n // we can just add to the slot contents because the\n // bytes we want to change are the LSBs\n fslot,\n add(\n mul(\n div(\n // load the bytes from memory\n mload(add(_postBytes, 0x20)),\n // zero all bytes to the right\n exp(0x100, sub(32, mlength))\n ),\n // and now shift left the number of bytes to\n // leave space for the length in the slot\n exp(0x100, sub(32, newlength))\n ),\n // increase length by the double of the memory\n // bytes length\n mul(mlength, 2)\n )\n )\n )\n }\n case 1 {\n // The stored value fits in the slot, but the combined value\n // will exceed it.\n // get the keccak hash to get the contents of the array\n mstore(0x0, _preBytes.slot)\n let sc := add(keccak256(0x0, 0x20), div(slength, 32))\n\n // save new length\n sstore(_preBytes.slot, add(mul(newlength, 2), 1))\n\n // The contents of the _postBytes array start 32 bytes into\n // the structure. Our first read should obtain the `submod`\n // bytes that can fit into the unused space in the last word\n // of the stored array. To get this, we read 32 bytes starting\n // from `submod`, so the data we read overlaps with the array\n // contents by `submod` bytes. Masking the lowest-order\n // `submod` bytes allows us to add that value directly to the\n // stored value.\n\n let submod := sub(32, slength)\n let mc := add(_postBytes, submod)\n let end := add(_postBytes, mlength)\n let mask := sub(exp(0x100, submod), 1)\n\n sstore(\n sc,\n add(\n and(\n fslot,\n 0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff00\n ),\n and(mload(mc), mask)\n )\n )\n\n for {\n mc := add(mc, 0x20)\n sc := add(sc, 1)\n } lt(mc, end) {\n sc := add(sc, 1)\n mc := add(mc, 0x20)\n } {\n sstore(sc, mload(mc))\n }\n\n mask := exp(0x100, sub(mc, end))\n\n sstore(sc, mul(div(mload(mc), mask), mask))\n }\n default {\n // get the keccak hash to get the contents of the array\n mstore(0x0, _preBytes.slot)\n // Start copying to the last used word of the stored array.\n let sc := add(keccak256(0x0, 0x20), div(slength, 32))\n\n // save new length\n sstore(_preBytes.slot, add(mul(newlength, 2), 1))\n\n // Copy over the first `submod` bytes of the new data as in\n // case 1 above.\n let slengthmod := mod(slength, 32)\n let submod := sub(32, slengthmod)\n let mc := add(_postBytes, submod)\n let end := add(_postBytes, mlength)\n let mask := sub(exp(0x100, submod), 1)\n\n sstore(sc, add(sload(sc), and(mload(mc), mask)))\n\n for {\n sc := add(sc, 1)\n mc := add(mc, 0x20)\n } lt(mc, end) {\n sc := add(sc, 1)\n mc := add(mc, 0x20)\n } {\n sstore(sc, mload(mc))\n }\n\n mask := exp(0x100, sub(mc, end))\n\n sstore(sc, mul(div(mload(mc), mask), mask))\n }\n }\n }\n\n function equalStorage(bytes storage _preBytes, bytes memory _postBytes)\n internal\n view\n returns (bool)\n {\n bool success = true;\n\n assembly {\n // we know _preBytes_offset is 0\n let fslot := sload(_preBytes.slot)\n // Decode the length of the stored array like in concatStorage().\n let slength := div(\n and(fslot, sub(mul(0x100, iszero(and(fslot, 1))), 1)),\n 2\n )\n let mlength := mload(_postBytes)\n\n // if lengths don't match the arrays are not equal\n switch eq(slength, mlength)\n case 1 {\n // slength can contain both the length and contents of the array\n // if length < 32 bytes so let's prepare for that\n // v. http://solidity.readthedocs.io/en/latest/miscellaneous.html#layout-of-state-variables-in-storage\n if iszero(iszero(slength)) {\n switch lt(slength, 32)\n case 1 {\n // blank the last byte which is the length\n fslot := mul(div(fslot, 0x100), 0x100)\n\n if iszero(eq(fslot, mload(add(_postBytes, 0x20)))) {\n // unsuccess:\n success := 0\n }\n }\n default {\n // cb is a circuit breaker in the for loop since there's\n // no said feature for inline assembly loops\n // cb = 1 - don't breaker\n // cb = 0 - break\n let cb := 1\n\n // get the keccak hash to get the contents of the array\n mstore(0x0, _preBytes.slot)\n let sc := keccak256(0x0, 0x20)\n\n let mc := add(_postBytes, 0x20)\n let end := add(mc, mlength)\n\n // the next line is the loop condition:\n // while(uint(mc < end) + cb == 2)\n for {\n\n } eq(add(lt(mc, end), cb), 2) {\n sc := add(sc, 1)\n mc := add(mc, 0x20)\n } {\n if iszero(eq(sload(sc), mload(mc))) {\n // unsuccess:\n success := 0\n cb := 0\n }\n }\n }\n }\n }\n default {\n // unsuccess:\n success := 0\n }\n }\n\n return success;\n }\n\n function concat(bytes memory _preBytes, bytes memory _postBytes)\n internal\n pure\n returns (bytes memory)\n {\n bytes memory tempBytes;\n\n assembly {\n // Get a location of some free memory and store it in tempBytes as\n // Solidity does for memory variables.\n tempBytes := mload(0x40)\n\n // Store the length of the first bytes array at the beginning of\n // the memory for tempBytes.\n let length := mload(_preBytes)\n mstore(tempBytes, length)\n\n // Maintain a memory counter for the current write location in the\n // temp bytes array by adding the 32 bytes for the array length to\n // the starting location.\n let mc := add(tempBytes, 0x20)\n // Stop copying when the memory counter reaches the length of the\n // first bytes array.\n let end := add(mc, length)\n\n for {\n // Initialize a copy counter to the start of the _preBytes data,\n // 32 bytes into its memory.\n let cc := add(_preBytes, 0x20)\n } lt(mc, end) {\n // Increase both counters by 32 bytes each iteration.\n mc := add(mc, 0x20)\n cc := add(cc, 0x20)\n } {\n // Write the _preBytes data into the tempBytes memory 32 bytes\n // at a time.\n mstore(mc, mload(cc))\n }\n\n // Add the length of _postBytes to the current length of tempBytes\n // and store it as the new length in the first 32 bytes of the\n // tempBytes memory.\n length := mload(_postBytes)\n mstore(tempBytes, add(length, mload(tempBytes)))\n\n // Move the memory counter back from a multiple of 0x20 to the\n // actual end of the _preBytes data.\n mc := end\n // Stop copying when the memory counter reaches the new combined\n // length of the arrays.\n end := add(mc, length)\n\n for {\n let cc := add(_postBytes, 0x20)\n } lt(mc, end) {\n mc := add(mc, 0x20)\n cc := add(cc, 0x20)\n } {\n mstore(mc, mload(cc))\n }\n\n // Update the free-memory pointer by padding our last write location\n // to 32 bytes: add 31 bytes to the end of tempBytes to move to the\n // next 32 byte block, then round down to the nearest multiple of\n // 32. If the sum of the length of the two arrays is zero then add\n // one before rounding down to leave a blank 32 bytes (the length block with 0).\n mstore(\n 0x40,\n and(\n add(add(end, iszero(add(length, mload(_preBytes)))), 31),\n not(31) // Round down to the nearest 32 bytes.\n )\n )\n }\n\n return tempBytes;\n }\n\n function slice(\n bytes memory _bytes,\n uint256 _start,\n uint256 _length\n ) internal pure returns (bytes memory res) {\n uint256 _end = _start + _length;\n require(_end > _start && _bytes.length >= _end, \"Slice out of bounds\");\n\n assembly {\n // Alloc bytes array with additional 32 bytes afterspace and assign it's size\n res := mload(0x40)\n mstore(0x40, add(add(res, 64), _length))\n mstore(res, _length)\n\n // Compute distance between source and destination pointers\n let diff := sub(res, add(_bytes, _start))\n\n for {\n let src := add(add(_bytes, 32), _start)\n let end := add(src, _length)\n } lt(src, end) {\n src := add(src, 32)\n } {\n mstore(add(src, diff), mload(src))\n }\n }\n }\n\n function toAddress(bytes memory _bytes, uint256 _start)\n internal\n pure\n returns (address)\n {\n uint256 _totalLen = _start + 20;\n require(\n _totalLen > _start && _bytes.length >= _totalLen,\n \"Address conversion out of bounds.\"\n );\n address tempAddress;\n\n assembly {\n tempAddress := div(\n mload(add(add(_bytes, 0x20), _start)),\n 0x1000000000000000000000000\n )\n }\n\n return tempAddress;\n }\n\n function toUint8(bytes memory _bytes, uint256 _start)\n internal\n pure\n returns (uint8)\n {\n require(\n _bytes.length >= (_start + 1),\n \"Uint8 conversion out of bounds.\"\n );\n uint8 tempUint;\n\n assembly {\n tempUint := mload(add(add(_bytes, 0x1), _start))\n }\n\n return tempUint;\n }\n\n function toUint(bytes memory _bytes, uint256 _start)\n internal\n pure\n returns (uint256)\n {\n uint256 _totalLen = _start + 32;\n require(\n _totalLen > _start && _bytes.length >= _totalLen,\n \"Uint conversion out of bounds.\"\n );\n uint256 tempUint;\n\n assembly {\n tempUint := mload(add(add(_bytes, 0x20), _start))\n }\n\n return tempUint;\n }\n\n function equal(bytes memory _preBytes, bytes memory _postBytes)\n internal\n pure\n returns (bool)\n {\n bool success = true;\n\n assembly {\n let length := mload(_preBytes)\n\n // if lengths don't match the arrays are not equal\n switch eq(length, mload(_postBytes))\n case 1 {\n // cb is a circuit breaker in the for loop since there's\n // no said feature for inline assembly loops\n // cb = 1 - don't breaker\n // cb = 0 - break\n let cb := 1\n\n let mc := add(_preBytes, 0x20)\n let end := add(mc, length)\n\n for {\n let cc := add(_postBytes, 0x20)\n // the next line is the loop condition:\n // while(uint(mc < end) + cb == 2)\n } eq(add(lt(mc, end), cb), 2) {\n mc := add(mc, 0x20)\n cc := add(cc, 0x20)\n } {\n // if any of these checks fails then arrays are not equal\n if iszero(eq(mload(mc), mload(cc))) {\n // unsuccess:\n success := 0\n cb := 0\n }\n }\n }\n default {\n // unsuccess:\n success := 0\n }\n }\n\n return success;\n }\n\n function toBytes32(bytes memory _source)\n internal\n pure\n returns (bytes32 result)\n {\n if (_source.length == 0) {\n return 0x0;\n }\n\n assembly {\n result := mload(add(_source, 32))\n }\n }\n\n function keccak256Slice(\n bytes memory _bytes,\n uint256 _start,\n uint256 _length\n ) internal pure returns (bytes32 result) {\n uint256 _end = _start + _length;\n require(_end > _start && _bytes.length >= _end, \"Slice out of bounds\");\n\n assembly {\n result := keccak256(add(add(_bytes, 32), _start), _length)\n }\n }\n}\n" + }, + "@keep-network/random-beacon/contracts/Reimbursable.sol": { + "content": "// SPDX-License-Identifier: GPL-3.0-only\n//\n// ▓▓▌ ▓▓ ▐▓▓ ▓▓▓▓▓▓▓▓▓▓▌▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▄\n// ▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▌▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓\n// ▓▓▓▓▓▓ ▓▓▓▓▓▓▓▀ ▐▓▓▓▓▓▓ ▐▓▓▓▓▓ ▓▓▓▓▓▓ ▓▓▓▓▓ ▐▓▓▓▓▓▌ ▐▓▓▓▓▓▓\n// ▓▓▓▓▓▓▄▄▓▓▓▓▓▓▓▀ ▐▓▓▓▓▓▓▄▄▄▄ ▓▓▓▓▓▓▄▄▄▄ ▐▓▓▓▓▓▌ ▐▓▓▓▓▓▓\n// ▓▓▓▓▓▓▓▓▓▓▓▓▓▀ ▐▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓\n// ▓▓▓▓▓▓▀▀▓▓▓▓▓▓▄ ▐▓▓▓▓▓▓▀▀▀▀ ▓▓▓▓▓▓▀▀▀▀ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▀\n// ▓▓▓▓▓▓ ▀▓▓▓▓▓▓▄ ▐▓▓▓▓▓▓ ▓▓▓▓▓ ▓▓▓▓▓▓ ▓▓▓▓▓ ▐▓▓▓▓▓▌\n// ▓▓▓▓▓▓▓▓▓▓ █▓▓▓▓▓▓▓▓▓ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓\n// ▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓\n//\n// Trust math, not hardware.\n\npragma solidity 0.8.17;\n\nimport \"./ReimbursementPool.sol\";\n\nabstract contract Reimbursable {\n // The variable should be initialized by the implementing contract.\n // slither-disable-next-line uninitialized-state\n ReimbursementPool public reimbursementPool;\n\n // Reserved storage space in case we need to add more variables,\n // since there are upgradeable contracts that inherit from this one.\n // See https://docs.openzeppelin.com/contracts/4.x/upgradeable#storage_gaps\n // slither-disable-next-line unused-state\n uint256[49] private __gap;\n\n event ReimbursementPoolUpdated(address newReimbursementPool);\n\n modifier refundable(address receiver) {\n uint256 gasStart = gasleft();\n _;\n reimbursementPool.refund(gasStart - gasleft(), receiver);\n }\n\n modifier onlyReimbursableAdmin() virtual {\n _;\n }\n\n function updateReimbursementPool(ReimbursementPool _reimbursementPool)\n external\n onlyReimbursableAdmin\n {\n emit ReimbursementPoolUpdated(address(_reimbursementPool));\n\n reimbursementPool = _reimbursementPool;\n }\n}\n" + }, + "@keep-network/random-beacon/contracts/ReimbursementPool.sol": { + "content": "// SPDX-License-Identifier: GPL-3.0-only\n//\n// ▓▓▌ ▓▓ ▐▓▓ ▓▓▓▓▓▓▓▓▓▓▌▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▄\n// ▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▌▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓\n// ▓▓▓▓▓▓ ▓▓▓▓▓▓▓▀ ▐▓▓▓▓▓▓ ▐▓▓▓▓▓ ▓▓▓▓▓▓ ▓▓▓▓▓ ▐▓▓▓▓▓▌ ▐▓▓▓▓▓▓\n// ▓▓▓▓▓▓▄▄▓▓▓▓▓▓▓▀ ▐▓▓▓▓▓▓▄▄▄▄ ▓▓▓▓▓▓▄▄▄▄ ▐▓▓▓▓▓▌ ▐▓▓▓▓▓▓\n// ▓▓▓▓▓▓▓▓▓▓▓▓▓▀ ▐▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓\n// ▓▓▓▓▓▓▀▀▓▓▓▓▓▓▄ ▐▓▓▓▓▓▓▀▀▀▀ ▓▓▓▓▓▓▀▀▀▀ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▀\n// ▓▓▓▓▓▓ ▀▓▓▓▓▓▓▄ ▐▓▓▓▓▓▓ ▓▓▓▓▓ ▓▓▓▓▓▓ ▓▓▓▓▓ ▐▓▓▓▓▓▌\n// ▓▓▓▓▓▓▓▓▓▓ █▓▓▓▓▓▓▓▓▓ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓\n// ▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓\n//\n// Trust math, not hardware.\n\npragma solidity 0.8.17;\n\nimport \"@openzeppelin/contracts/access/Ownable.sol\";\nimport \"@openzeppelin/contracts/security/ReentrancyGuard.sol\";\n\ncontract ReimbursementPool is Ownable, ReentrancyGuard {\n /// @notice Authorized contracts that can interact with the reimbursment pool.\n /// Authorization can be granted and removed by the owner.\n mapping(address => bool) public isAuthorized;\n\n /// @notice Static gas includes:\n /// - cost of the refund function\n /// - base transaction cost\n uint256 public staticGas;\n\n /// @notice Max gas price used to reimburse a transaction submitter. Protects\n /// against malicious operator-miners.\n uint256 public maxGasPrice;\n\n event StaticGasUpdated(uint256 newStaticGas);\n\n event MaxGasPriceUpdated(uint256 newMaxGasPrice);\n\n event SendingEtherFailed(uint256 refundAmount, address receiver);\n\n event AuthorizedContract(address thirdPartyContract);\n\n event UnauthorizedContract(address thirdPartyContract);\n\n event FundsWithdrawn(uint256 withdrawnAmount, address receiver);\n\n constructor(uint256 _staticGas, uint256 _maxGasPrice) {\n staticGas = _staticGas;\n maxGasPrice = _maxGasPrice;\n }\n\n /// @notice Receive ETH\n receive() external payable {}\n\n /// @notice Refunds ETH to a spender for executing specific transactions.\n /// @dev Ignoring the result of sending ETH to a receiver is made on purpose.\n /// For EOA receiving ETH should always work. If a receiver is a smart\n /// contract, then we do not want to fail a transaction, because in some\n /// cases the refund is done at the very end of multiple calls where all\n /// the previous calls were already paid off. It is a receiver's smart\n /// contract resposibility to make sure it can receive ETH.\n /// @dev Only authorized contracts are allowed calling this function.\n /// @param gasSpent Gas spent on a transaction that needs to be reimbursed.\n /// @param receiver Address where the reimbursment is sent.\n function refund(uint256 gasSpent, address receiver) external nonReentrant {\n require(\n isAuthorized[msg.sender],\n \"Contract is not authorized for a refund\"\n );\n require(receiver != address(0), \"Receiver's address cannot be zero\");\n\n uint256 gasPrice = tx.gasprice < maxGasPrice\n ? tx.gasprice\n : maxGasPrice;\n\n uint256 refundAmount = (gasSpent + staticGas) * gasPrice;\n\n /* solhint-disable avoid-low-level-calls */\n // slither-disable-next-line low-level-calls,unchecked-lowlevel\n (bool sent, ) = receiver.call{value: refundAmount}(\"\");\n /* solhint-enable avoid-low-level-calls */\n if (!sent) {\n // slither-disable-next-line reentrancy-events\n emit SendingEtherFailed(refundAmount, receiver);\n }\n }\n\n /// @notice Authorize a contract that can interact with this reimbursment pool.\n /// Can be authorized by the owner only.\n /// @param _contract Authorized contract.\n function authorize(address _contract) external onlyOwner {\n isAuthorized[_contract] = true;\n\n emit AuthorizedContract(_contract);\n }\n\n /// @notice Unauthorize a contract that was previously authorized to interact\n /// with this reimbursment pool. Can be unauthorized by the\n /// owner only.\n /// @param _contract Authorized contract.\n function unauthorize(address _contract) external onlyOwner {\n delete isAuthorized[_contract];\n\n emit UnauthorizedContract(_contract);\n }\n\n /// @notice Setting a static gas cost for executing a transaction. Can be set\n /// by the owner only.\n /// @param _staticGas Static gas cost.\n function setStaticGas(uint256 _staticGas) external onlyOwner {\n staticGas = _staticGas;\n\n emit StaticGasUpdated(_staticGas);\n }\n\n /// @notice Setting a max gas price for transactions. Can be set by the\n /// owner only.\n /// @param _maxGasPrice Max gas price used to reimburse tx submitters.\n function setMaxGasPrice(uint256 _maxGasPrice) external onlyOwner {\n maxGasPrice = _maxGasPrice;\n\n emit MaxGasPriceUpdated(_maxGasPrice);\n }\n\n /// @notice Withdraws all ETH from this pool which are sent to a given\n /// address. Can be set by the owner only.\n /// @param receiver An address where ETH is sent.\n function withdrawAll(address receiver) external onlyOwner {\n withdraw(address(this).balance, receiver);\n }\n\n /// @notice Withdraws ETH amount from this pool which are sent to a given\n /// address. Can be set by the owner only.\n /// @param amount Amount to withdraw from the pool.\n /// @param receiver An address where ETH is sent.\n function withdraw(uint256 amount, address receiver) public onlyOwner {\n require(\n address(this).balance >= amount,\n \"Insufficient contract balance\"\n );\n require(receiver != address(0), \"Receiver's address cannot be zero\");\n\n emit FundsWithdrawn(amount, receiver);\n\n /* solhint-disable avoid-low-level-calls */\n // slither-disable-next-line low-level-calls,arbitrary-send\n (bool sent, ) = receiver.call{value: amount}(\"\");\n /* solhint-enable avoid-low-level-calls */\n require(sent, \"Failed to send Ether\");\n }\n}\n" + }, + "@keep-network/sortition-pools/contracts/Branch.sol": { + "content": "pragma solidity 0.8.17;\n\nimport \"./Constants.sol\";\n\n/// @notice The implicit 8-ary trees of the sortition pool\n/// rely on packing 8 \"slots\" of 32-bit values into each uint256.\n/// The Branch library permits efficient calculations on these slots.\nlibrary Branch {\n /// @notice Calculate the right shift required\n /// to make the 32 least significant bits of an uint256\n /// be the bits of the `position`th slot\n /// when treating the uint256 as a uint32[8].\n ///\n /// @dev Not used for efficiency reasons,\n /// but left to illustrate the meaning of a common pattern.\n /// I wish solidity had macros, even C macros.\n function slotShift(uint256 position) internal pure returns (uint256) {\n unchecked {\n return position * Constants.SLOT_WIDTH;\n }\n }\n\n /// @notice Return the `position`th slot of the `node`,\n /// treating `node` as a uint32[32].\n function getSlot(uint256 node, uint256 position)\n internal\n pure\n returns (uint256)\n {\n unchecked {\n uint256 shiftBits = position * Constants.SLOT_WIDTH;\n // Doing a bitwise AND with `SLOT_MAX`\n // clears all but the 32 least significant bits.\n // Because of the right shift by `slotShift(position)` bits,\n // those 32 bits contain the 32 bits in the `position`th slot of `node`.\n return (node >> shiftBits) & Constants.SLOT_MAX;\n }\n }\n\n /// @notice Return `node` with the `position`th slot set to zero.\n function clearSlot(uint256 node, uint256 position)\n internal\n pure\n returns (uint256)\n {\n unchecked {\n uint256 shiftBits = position * Constants.SLOT_WIDTH;\n // Shifting `SLOT_MAX` left by `slotShift(position)` bits\n // gives us a number where all bits of the `position`th slot are set,\n // and all other bits are unset.\n //\n // Using a bitwise NOT on this number,\n // we get a uint256 where all bits are set\n // except for those of the `position`th slot.\n //\n // Bitwise ANDing the original `node` with this number\n // sets the bits of `position`th slot to zero,\n // leaving all other bits unchanged.\n return node & ~(Constants.SLOT_MAX << shiftBits);\n }\n }\n\n /// @notice Return `node` with the `position`th slot set to `weight`.\n ///\n /// @param weight The weight of of the node.\n /// Safely truncated to a 32-bit number,\n /// but this should never be called with an overflowing weight regardless.\n function setSlot(\n uint256 node,\n uint256 position,\n uint256 weight\n ) internal pure returns (uint256) {\n unchecked {\n uint256 shiftBits = position * Constants.SLOT_WIDTH;\n // Clear the `position`th slot like in `clearSlot()`.\n uint256 clearedNode = node & ~(Constants.SLOT_MAX << shiftBits);\n // Bitwise AND `weight` with `SLOT_MAX`\n // to clear all but the 32 least significant bits.\n //\n // Shift this left by `slotShift(position)` bits\n // to obtain a uint256 with all bits unset\n // except in the `position`th slot\n // which contains the 32-bit value of `weight`.\n uint256 shiftedWeight = (weight & Constants.SLOT_MAX) << shiftBits;\n // When we bitwise OR these together,\n // all other slots except the `position`th one come from the left argument,\n // and the `position`th gets filled with `weight` from the right argument.\n return clearedNode | shiftedWeight;\n }\n }\n\n /// @notice Calculate the summed weight of all slots in the `node`.\n function sumWeight(uint256 node) internal pure returns (uint256 sum) {\n unchecked {\n sum = node & Constants.SLOT_MAX;\n // Iterate through each slot\n // by shifting `node` right in increments of 32 bits,\n // and adding the 32 least significant bits to the `sum`.\n uint256 newNode = node >> Constants.SLOT_WIDTH;\n while (newNode > 0) {\n sum += (newNode & Constants.SLOT_MAX);\n newNode = newNode >> Constants.SLOT_WIDTH;\n }\n return sum;\n }\n }\n\n /// @notice Pick a slot in `node` that corresponds to `index`.\n /// Treats the node like an array of virtual stakers,\n /// the number of virtual stakers in each slot corresponding to its weight,\n /// and picks which slot contains the `index`th virtual staker.\n ///\n /// @dev Requires that `index` be lower than `sumWeight(node)`.\n /// However, this is not enforced for performance reasons.\n /// If `index` exceeds the permitted range,\n /// `pickWeightedSlot()` returns the rightmost slot\n /// and an excessively high `newIndex`.\n ///\n /// @return slot The slot of `node` containing the `index`th virtual staker.\n ///\n /// @return newIndex The index of the `index`th virtual staker of `node`\n /// within the returned slot.\n function pickWeightedSlot(uint256 node, uint256 index)\n internal\n pure\n returns (uint256 slot, uint256 newIndex)\n {\n unchecked {\n newIndex = index;\n uint256 newNode = node;\n uint256 currentSlotWeight = newNode & Constants.SLOT_MAX;\n while (newIndex >= currentSlotWeight) {\n newIndex -= currentSlotWeight;\n slot++;\n newNode = newNode >> Constants.SLOT_WIDTH;\n currentSlotWeight = newNode & Constants.SLOT_MAX;\n }\n return (slot, newIndex);\n }\n }\n}\n" + }, + "@keep-network/sortition-pools/contracts/Chaosnet.sol": { + "content": "pragma solidity 0.8.17;\n\n/// @title Chaosnet\n/// @notice This is a beta staker program for stakers willing to go the extra\n/// mile with monitoring, share their logs with the dev team, and allow to more\n/// carefully monitor the bootstrapping network. As the network matures, the\n/// beta program will be ended.\ncontract Chaosnet {\n /// @notice Indicates if the chaosnet is active. The chaosnet is active\n /// after the contract deployment and can be ended with a call to\n /// `deactivateChaosnet()`. Once deactivated chaosnet can not be activated\n /// again.\n bool public isChaosnetActive;\n\n /// @notice Indicates if the given operator is a beta operator for chaosnet.\n mapping(address => bool) public isBetaOperator;\n\n /// @notice Address controlling chaosnet status and beta operator addresses.\n address public chaosnetOwner;\n\n event BetaOperatorsAdded(address[] operators);\n\n event ChaosnetOwnerRoleTransferred(\n address oldChaosnetOwner,\n address newChaosnetOwner\n );\n\n event ChaosnetDeactivated();\n\n constructor() {\n _transferChaosnetOwner(msg.sender);\n isChaosnetActive = true;\n }\n\n modifier onlyChaosnetOwner() {\n require(msg.sender == chaosnetOwner, \"Not the chaosnet owner\");\n _;\n }\n\n modifier onlyOnChaosnet() {\n require(isChaosnetActive, \"Chaosnet is not active\");\n _;\n }\n\n /// @notice Adds beta operator to chaosnet. Can be called only by the\n /// chaosnet owner when the chaosnet is active. Once the operator is added\n /// as a beta operator, it can not be removed.\n function addBetaOperators(address[] calldata operators)\n public\n onlyOnChaosnet\n onlyChaosnetOwner\n {\n for (uint256 i = 0; i < operators.length; i++) {\n isBetaOperator[operators[i]] = true;\n }\n\n emit BetaOperatorsAdded(operators);\n }\n\n /// @notice Deactivates the chaosnet. Can be called only by the chaosnet\n /// owner. Once deactivated chaosnet can not be activated again.\n function deactivateChaosnet() public onlyOnChaosnet onlyChaosnetOwner {\n isChaosnetActive = false;\n emit ChaosnetDeactivated();\n }\n\n /// @notice Transfers the chaosnet owner role to another non-zero address.\n function transferChaosnetOwnerRole(address newChaosnetOwner)\n public\n onlyChaosnetOwner\n {\n require(\n newChaosnetOwner != address(0),\n \"New chaosnet owner must not be zero address\"\n );\n _transferChaosnetOwner(newChaosnetOwner);\n }\n\n function _transferChaosnetOwner(address newChaosnetOwner) internal {\n address oldChaosnetOwner = chaosnetOwner;\n chaosnetOwner = newChaosnetOwner;\n emit ChaosnetOwnerRoleTransferred(oldChaosnetOwner, newChaosnetOwner);\n }\n}\n" + }, + "@keep-network/sortition-pools/contracts/Constants.sol": { + "content": "pragma solidity 0.8.17;\n\nlibrary Constants {\n ////////////////////////////////////////////////////////////////////////////\n // Parameters for configuration\n\n // How many bits a position uses per level of the tree;\n // each branch of the tree contains 2**SLOT_BITS slots.\n uint256 constant SLOT_BITS = 3;\n uint256 constant LEVELS = 7;\n ////////////////////////////////////////////////////////////////////////////\n\n ////////////////////////////////////////////////////////////////////////////\n // Derived constants, do not touch\n uint256 constant SLOT_COUNT = 2**SLOT_BITS;\n uint256 constant SLOT_WIDTH = 256 / SLOT_COUNT;\n uint256 constant LAST_SLOT = SLOT_COUNT - 1;\n uint256 constant SLOT_MAX = (2**SLOT_WIDTH) - 1;\n uint256 constant POOL_CAPACITY = SLOT_COUNT**LEVELS;\n\n uint256 constant ID_WIDTH = SLOT_WIDTH;\n uint256 constant ID_MAX = SLOT_MAX;\n\n uint256 constant BLOCKHEIGHT_WIDTH = 96 - ID_WIDTH;\n uint256 constant BLOCKHEIGHT_MAX = (2**BLOCKHEIGHT_WIDTH) - 1;\n\n uint256 constant SLOT_POINTER_MAX = (2**SLOT_BITS) - 1;\n uint256 constant LEAF_FLAG = 1 << 255;\n\n uint256 constant WEIGHT_WIDTH = 256 / SLOT_COUNT;\n ////////////////////////////////////////////////////////////////////////////\n}\n" + }, + "@keep-network/sortition-pools/contracts/Leaf.sol": { + "content": "pragma solidity 0.8.17;\n\nimport \"./Constants.sol\";\n\nlibrary Leaf {\n function make(\n address _operator,\n uint256 _creationBlock,\n uint256 _id\n ) internal pure returns (uint256) {\n assert(_creationBlock <= type(uint64).max);\n assert(_id <= type(uint32).max);\n // Converting a bytesX type into a larger type\n // adds zero bytes on the right.\n uint256 op = uint256(bytes32(bytes20(_operator)));\n // Bitwise AND the id to erase\n // all but the 32 least significant bits\n uint256 uid = _id & Constants.ID_MAX;\n // Erase all but the 64 least significant bits,\n // then shift left by 32 bits to make room for the id\n uint256 cb = (_creationBlock & Constants.BLOCKHEIGHT_MAX) <<\n Constants.ID_WIDTH;\n // Bitwise OR them all together to get\n // [address operator || uint64 creationBlock || uint32 id]\n return (op | cb | uid);\n }\n\n function operator(uint256 leaf) internal pure returns (address) {\n // Converting a bytesX type into a smaller type\n // truncates it on the right.\n return address(bytes20(bytes32(leaf)));\n }\n\n /// @notice Return the block number the leaf was created in.\n function creationBlock(uint256 leaf) internal pure returns (uint256) {\n return ((leaf >> Constants.ID_WIDTH) & Constants.BLOCKHEIGHT_MAX);\n }\n\n function id(uint256 leaf) internal pure returns (uint32) {\n // Id is stored in the 32 least significant bits.\n // Bitwise AND ensures that we only get the contents of those bits.\n return uint32(leaf & Constants.ID_MAX);\n }\n}\n" + }, + "@keep-network/sortition-pools/contracts/Position.sol": { + "content": "pragma solidity 0.8.17;\n\nimport \"./Constants.sol\";\n\nlibrary Position {\n // Return the last 3 bits of a position number,\n // corresponding to its slot in its parent\n function slot(uint256 a) internal pure returns (uint256) {\n return a & Constants.SLOT_POINTER_MAX;\n }\n\n // Return the parent of a position number\n function parent(uint256 a) internal pure returns (uint256) {\n return a >> Constants.SLOT_BITS;\n }\n\n // Return the location of the child of a at the given slot\n function child(uint256 a, uint256 s) internal pure returns (uint256) {\n return (a << Constants.SLOT_BITS) | (s & Constants.SLOT_POINTER_MAX); // slot(s)\n }\n\n // Return the uint p as a flagged position uint:\n // the least significant 21 bits contain the position\n // and the 22nd bit is set as a flag\n // to distinguish the position 0x000000 from an empty field.\n function setFlag(uint256 p) internal pure returns (uint256) {\n return p | Constants.LEAF_FLAG;\n }\n\n // Turn a flagged position into an unflagged position\n // by removing the flag at the 22nd least significant bit.\n //\n // We shouldn't _actually_ need this\n // as all position-manipulating code should ignore non-position bits anyway\n // but it's cheap to call so might as well do it.\n function unsetFlag(uint256 p) internal pure returns (uint256) {\n return p & (~Constants.LEAF_FLAG);\n }\n}\n" + }, + "@keep-network/sortition-pools/contracts/Rewards.sol": { + "content": "pragma solidity 0.8.17;\n\n/// @title Rewards\n/// @notice Rewards are allocated proportionally to operators\n/// present in the pool at payout based on their weight in the pool.\n///\n/// To facilitate this, we use a global accumulator value\n/// to track the total rewards one unit of weight would've earned\n/// since the creation of the pool.\n///\n/// Whenever a reward is paid, the accumulator is increased\n/// by the size of the reward divided by the total weight\n/// of all eligible operators in the pool.\n///\n/// Each operator has an individual accumulator value,\n/// set to equal the global accumulator when the operator joins the pool.\n/// This accumulator reflects the amount of rewards\n/// that have already been accounted for with that operator.\n///\n/// Whenever an operator's weight in the pool changes,\n/// we can update the amount of rewards the operator has earned\n/// by subtracting the operator's accumulator from the global accumulator.\n/// This gives us the amount of rewards one unit of weight has earned\n/// since the last time the operator's rewards have been updated.\n/// Then we multiply that by the operator's previous (pre-change) weight\n/// to determine how much rewards in total the operator has earned,\n/// and add this to the operator's earned rewards.\n/// Finally, we set the operator's accumulator to the global accumulator value.\ncontract Rewards {\n struct OperatorRewards {\n // The state of the global accumulator\n // when the operator's rewards were last updated\n uint96 accumulated;\n // The amount of rewards collected by the operator after the latest update.\n // The amount the operator could withdraw may equal `available`\n // or it may be greater, if more rewards have been paid in since then.\n // To evaulate the most recent amount including rewards potentially paid\n // since the last update, use `availableRewards` function.\n uint96 available;\n // If nonzero, the operator is ineligible for rewards\n // and may only re-enable rewards after the specified timestamp.\n // XXX: unsigned 32-bit integer unix seconds, will break around 2106\n uint32 ineligibleUntil;\n // Locally cached weight of the operator,\n // used to reduce the cost of setting operators ineligible.\n uint32 weight;\n }\n\n // The global accumulator of how much rewards\n // a hypothetical operator of weight 1 would have earned\n // since the creation of the pool.\n uint96 internal globalRewardAccumulator;\n // If the amount of reward tokens paid in\n // does not divide cleanly by pool weight,\n // the difference is recorded as rounding dust\n // and added to the next reward.\n uint96 internal rewardRoundingDust;\n\n // The amount of rewards that would've been earned by ineligible operators\n // had they not been ineligible.\n uint96 public ineligibleEarnedRewards;\n\n // Ineligibility times are calculated from this offset,\n // set at contract creation.\n uint256 internal immutable ineligibleOffsetStart;\n\n mapping(uint32 => OperatorRewards) internal operatorRewards;\n\n constructor() {\n // solhint-disable-next-line not-rely-on-time\n ineligibleOffsetStart = block.timestamp;\n }\n\n /// @notice Return whether the operator is eligible for rewards or not.\n function isEligibleForRewards(uint32 operator) internal view returns (bool) {\n return operatorRewards[operator].ineligibleUntil == 0;\n }\n\n /// @notice Return the time the operator's reward eligibility can be restored.\n function rewardsEligibilityRestorableAt(uint32 operator)\n internal\n view\n returns (uint256)\n {\n uint32 until = operatorRewards[operator].ineligibleUntil;\n require(until != 0, \"Operator already eligible\");\n return (uint256(until) + ineligibleOffsetStart);\n }\n\n /// @notice Return whether the operator is able to restore their eligibility\n /// for rewards right away.\n function canRestoreRewardEligibility(uint32 operator)\n internal\n view\n returns (bool)\n {\n // solhint-disable-next-line not-rely-on-time\n return rewardsEligibilityRestorableAt(operator) <= block.timestamp;\n }\n\n /// @notice Internal function for updating the global state of rewards.\n function addRewards(uint96 rewardAmount, uint32 currentPoolWeight) internal {\n require(currentPoolWeight > 0, \"No recipients in pool\");\n\n uint96 totalAmount = rewardAmount + rewardRoundingDust;\n uint96 perWeightReward = totalAmount / currentPoolWeight;\n uint96 newRoundingDust = totalAmount % currentPoolWeight;\n\n globalRewardAccumulator += perWeightReward;\n rewardRoundingDust = newRoundingDust;\n }\n\n /// @notice Internal function for updating the operator's reward state.\n function updateOperatorRewards(uint32 operator, uint32 newWeight) internal {\n uint96 acc = globalRewardAccumulator;\n OperatorRewards memory o = operatorRewards[operator];\n uint96 accruedRewards = (acc - o.accumulated) * uint96(o.weight);\n if (o.ineligibleUntil == 0) {\n // If operator is not ineligible, update their earned rewards\n o.available += accruedRewards;\n } else {\n // If ineligible, put the rewards into the ineligible pot\n ineligibleEarnedRewards += accruedRewards;\n }\n // In any case, update their accumulator and weight\n o.accumulated = acc;\n o.weight = newWeight;\n operatorRewards[operator] = o;\n }\n\n /// @notice Set the amount of withdrawable tokens to zero\n /// and return the previous withdrawable amount.\n /// @dev Does not update the withdrawable amount,\n /// but should usually be accompanied by an update.\n function withdrawOperatorRewards(uint32 operator)\n internal\n returns (uint96 withdrawable)\n {\n OperatorRewards storage o = operatorRewards[operator];\n withdrawable = o.available;\n o.available = 0;\n }\n\n /// @notice Set the amount of ineligible-earned tokens to zero\n /// and return the previous amount.\n function withdrawIneligibleRewards() internal returns (uint96 withdrawable) {\n withdrawable = ineligibleEarnedRewards;\n ineligibleEarnedRewards = 0;\n }\n\n /// @notice Set the given operators as ineligible for rewards.\n /// The operators can restore their eligibility at the given time.\n function setIneligible(uint32[] memory operators, uint256 until) internal {\n OperatorRewards memory o = OperatorRewards(0, 0, 0, 0);\n uint96 globalAcc = globalRewardAccumulator;\n uint96 accrued = 0;\n // Record ineligibility as seconds after contract creation\n uint32 _until = uint32(until - ineligibleOffsetStart);\n\n for (uint256 i = 0; i < operators.length; i++) {\n uint32 operator = operators[i];\n OperatorRewards storage r = operatorRewards[operator];\n o.available = r.available;\n o.accumulated = r.accumulated;\n o.ineligibleUntil = r.ineligibleUntil;\n o.weight = r.weight;\n\n if (o.ineligibleUntil != 0) {\n // If operator is already ineligible,\n // don't earn rewards or shorten its ineligibility\n if (o.ineligibleUntil < _until) {\n o.ineligibleUntil = _until;\n }\n } else {\n // The operator becomes ineligible -> earn rewards\n o.ineligibleUntil = _until;\n accrued = (globalAcc - o.accumulated) * uint96(o.weight);\n o.available += accrued;\n }\n o.accumulated = globalAcc;\n\n r.available = o.available;\n r.accumulated = o.accumulated;\n r.ineligibleUntil = o.ineligibleUntil;\n r.weight = o.weight;\n }\n }\n\n /// @notice Restore the given operator's eligibility for rewards.\n function restoreEligibility(uint32 operator) internal {\n // solhint-disable-next-line not-rely-on-time\n require(canRestoreRewardEligibility(operator), \"Operator still ineligible\");\n uint96 acc = globalRewardAccumulator;\n OperatorRewards memory o = operatorRewards[operator];\n uint96 accruedRewards = (acc - o.accumulated) * uint96(o.weight);\n ineligibleEarnedRewards += accruedRewards;\n o.accumulated = acc;\n o.ineligibleUntil = 0;\n operatorRewards[operator] = o;\n }\n\n /// @notice Returns the amount of rewards currently available for withdrawal\n /// for the given operator.\n function availableRewards(uint32 operator) internal view returns (uint96) {\n uint96 acc = globalRewardAccumulator;\n OperatorRewards memory o = operatorRewards[operator];\n if (o.ineligibleUntil == 0) {\n // If operator is not ineligible, calculate newly accrued rewards and add\n // them to the available ones, calculated during the last update.\n uint96 accruedRewards = (acc - o.accumulated) * uint96(o.weight);\n return o.available + accruedRewards;\n } else {\n // If ineligible, return only the rewards calculated during the last\n // update.\n return o.available;\n }\n }\n}\n" + }, + "@keep-network/sortition-pools/contracts/RNG.sol": { + "content": "pragma solidity 0.8.17;\n\nimport \"./Leaf.sol\";\nimport \"./Constants.sol\";\n\nlibrary RNG {\n /// @notice Get an index in the range `[0 .. range-1]`\n /// and the new state of the RNG,\n /// using the provided `state` of the RNG.\n ///\n /// @param range The upper bound of the index, exclusive.\n ///\n /// @param state The previous state of the RNG.\n /// The initial state needs to be obtained\n /// from a trusted randomness oracle (the random beacon),\n /// or from a chain of earlier calls to `RNG.getIndex()`\n /// on an originally trusted seed.\n ///\n /// @dev Calculates the number of bits required for the desired range,\n /// takes the least significant bits of `state`\n /// and checks if the obtained index is within the desired range.\n /// The original state is hashed with `keccak256` to get a new state.\n /// If the index is outside the range,\n /// the function retries until it gets a suitable index.\n ///\n /// @return index A random integer between `0` and `range - 1`, inclusive.\n ///\n /// @return newState The new state of the RNG.\n /// When `getIndex()` is called one or more times,\n /// care must be taken to always use the output `state`\n /// of the most recent call as the input `state` of a subsequent call.\n /// At the end of a transaction calling `RNG.getIndex()`,\n /// the previous stored state must be overwritten with the latest output.\n function getIndex(\n uint256 range,\n bytes32 state,\n uint256 bits\n ) internal view returns (uint256, bytes32) {\n bool found = false;\n uint256 index = 0;\n bytes32 newState = state;\n while (!found) {\n index = truncate(bits, uint256(newState));\n newState = keccak256(abi.encodePacked(newState, address(this)));\n if (index < range) {\n found = true;\n }\n }\n return (index, newState);\n }\n\n /// @notice Calculate how many bits are required\n /// for an index in the range `[0 .. range-1]`.\n ///\n /// @param range The upper bound of the desired range, exclusive.\n ///\n /// @return uint The smallest number of bits\n /// that can contain the number `range-1`.\n function bitsRequired(uint256 range) internal pure returns (uint256) {\n unchecked {\n if (range == 1) {\n return 0;\n }\n\n uint256 bits = Constants.WEIGHT_WIDTH - 1;\n\n // Left shift by `bits`,\n // so we have a 1 in the (bits + 1)th least significant bit\n // and 0 in other bits.\n // If this number is equal or greater than `range`,\n // the range [0, range-1] fits in `bits` bits.\n //\n // Because we loop from high bits to low bits,\n // we find the highest number of bits that doesn't fit the range,\n // and return that number + 1.\n while (1 << bits >= range) {\n bits--;\n }\n\n return bits + 1;\n }\n }\n\n /// @notice Truncate `input` to the `bits` least significant bits.\n function truncate(uint256 bits, uint256 input)\n internal\n pure\n returns (uint256)\n {\n unchecked {\n return input & ((1 << bits) - 1);\n }\n }\n}\n" + }, + "@keep-network/sortition-pools/contracts/SortitionPool.sol": { + "content": "pragma solidity 0.8.17;\n\nimport \"@thesis/solidity-contracts/contracts/token/IERC20WithPermit.sol\";\nimport \"@thesis/solidity-contracts/contracts/token/IReceiveApproval.sol\";\n\nimport \"@openzeppelin/contracts/access/Ownable.sol\";\n\nimport \"./RNG.sol\";\nimport \"./SortitionTree.sol\";\nimport \"./Rewards.sol\";\nimport \"./Chaosnet.sol\";\n\n/// @title Sortition Pool\n/// @notice A logarithmic data structure used to store the pool of eligible\n/// operators weighted by their stakes. It allows to select a group of operators\n/// based on the provided pseudo-random seed.\ncontract SortitionPool is\n SortitionTree,\n Rewards,\n Ownable,\n Chaosnet,\n IReceiveApproval\n{\n using Branch for uint256;\n using Leaf for uint256;\n using Position for uint256;\n\n IERC20WithPermit public immutable rewardToken;\n\n uint256 public immutable poolWeightDivisor;\n\n bool public isLocked;\n\n event IneligibleForRewards(uint32[] ids, uint256 until);\n\n event RewardEligibilityRestored(address indexed operator, uint32 indexed id);\n\n /// @notice Reverts if called while pool is locked.\n modifier onlyUnlocked() {\n require(!isLocked, \"Sortition pool locked\");\n _;\n }\n\n /// @notice Reverts if called while pool is unlocked.\n modifier onlyLocked() {\n require(isLocked, \"Sortition pool unlocked\");\n _;\n }\n\n constructor(IERC20WithPermit _rewardToken, uint256 _poolWeightDivisor) {\n rewardToken = _rewardToken;\n poolWeightDivisor = _poolWeightDivisor;\n }\n\n function receiveApproval(\n address sender,\n uint256 amount,\n address token,\n bytes calldata\n ) external override {\n require(token == address(rewardToken), \"Unsupported token\");\n rewardToken.transferFrom(sender, address(this), amount);\n Rewards.addRewards(uint96(amount), uint32(root.sumWeight()));\n }\n\n /// @notice Withdraws all available rewards for the given operator to the\n /// given beneficiary.\n /// @dev Can be called only be the owner. Does not validate if the provided\n /// beneficiary is associated with the provided operator - this needs to\n /// be done by the owner calling this function.\n /// @return The amount of rewards withdrawn in this call.\n function withdrawRewards(address operator, address beneficiary)\n public\n onlyOwner\n returns (uint96)\n {\n uint32 id = getOperatorID(operator);\n Rewards.updateOperatorRewards(id, uint32(getPoolWeight(operator)));\n uint96 earned = Rewards.withdrawOperatorRewards(id);\n rewardToken.transfer(beneficiary, uint256(earned));\n return earned;\n }\n\n /// @notice Withdraws rewards not allocated to operators marked as ineligible\n /// to the given recipient address.\n /// @dev Can be called only by the owner.\n function withdrawIneligible(address recipient) public onlyOwner {\n uint96 earned = Rewards.withdrawIneligibleRewards();\n rewardToken.transfer(recipient, uint256(earned));\n }\n\n /// @notice Locks the sortition pool. In locked state, members cannot be\n /// inserted and removed from the pool. Members statuses cannot\n /// be updated as well.\n /// @dev Can be called only by the contract owner.\n function lock() public onlyOwner {\n isLocked = true;\n }\n\n /// @notice Unlocks the sortition pool. Removes all restrictions set by\n /// the `lock` method.\n /// @dev Can be called only by the contract owner.\n function unlock() public onlyOwner {\n isLocked = false;\n }\n\n /// @notice Inserts an operator to the pool. Reverts if the operator is\n /// already present. Reverts if the operator is not eligible because of their\n /// authorized stake. Reverts if the chaosnet is active and the operator is\n /// not a beta operator.\n /// @dev Can be called only by the contract owner.\n /// @param operator Address of the inserted operator.\n /// @param authorizedStake Inserted operator's authorized stake for the application.\n function insertOperator(address operator, uint256 authorizedStake)\n public\n onlyOwner\n onlyUnlocked\n {\n uint256 weight = getWeight(authorizedStake);\n require(weight > 0, \"Operator not eligible\");\n\n if (isChaosnetActive) {\n require(isBetaOperator[operator], \"Not beta operator for chaosnet\");\n }\n\n _insertOperator(operator, weight);\n uint32 id = getOperatorID(operator);\n Rewards.updateOperatorRewards(id, uint32(weight));\n }\n\n /// @notice Update the operator's weight if present and eligible,\n /// or remove from the pool if present and ineligible.\n /// @dev Can be called only by the contract owner.\n /// @param operator Address of the updated operator.\n /// @param authorizedStake Operator's authorized stake for the application.\n function updateOperatorStatus(address operator, uint256 authorizedStake)\n public\n onlyOwner\n onlyUnlocked\n {\n uint256 weight = getWeight(authorizedStake);\n\n uint32 id = getOperatorID(operator);\n Rewards.updateOperatorRewards(id, uint32(weight));\n\n if (weight == 0) {\n _removeOperator(operator);\n } else {\n updateOperator(operator, weight);\n }\n }\n\n /// @notice Set the given operators as ineligible for rewards.\n /// The operators can restore their eligibility at the given time.\n function setRewardIneligibility(uint32[] calldata operators, uint256 until)\n public\n onlyOwner\n {\n Rewards.setIneligible(operators, until);\n emit IneligibleForRewards(operators, until);\n }\n\n /// @notice Restores reward eligibility for the operator.\n function restoreRewardEligibility(address operator) public {\n uint32 id = getOperatorID(operator);\n Rewards.restoreEligibility(id);\n emit RewardEligibilityRestored(operator, id);\n }\n\n /// @notice Returns whether the operator is eligible for rewards or not.\n function isEligibleForRewards(address operator) public view returns (bool) {\n uint32 id = getOperatorID(operator);\n return Rewards.isEligibleForRewards(id);\n }\n\n /// @notice Returns the time the operator's reward eligibility can be restored.\n function rewardsEligibilityRestorableAt(address operator)\n public\n view\n returns (uint256)\n {\n uint32 id = getOperatorID(operator);\n return Rewards.rewardsEligibilityRestorableAt(id);\n }\n\n /// @notice Returns whether the operator is able to restore their eligibility\n /// for rewards right away.\n function canRestoreRewardEligibility(address operator)\n public\n view\n returns (bool)\n {\n uint32 id = getOperatorID(operator);\n return Rewards.canRestoreRewardEligibility(id);\n }\n\n /// @notice Returns the amount of rewards withdrawable for the given operator.\n function getAvailableRewards(address operator) public view returns (uint96) {\n uint32 id = getOperatorID(operator);\n return availableRewards(id);\n }\n\n /// @notice Return whether the operator is present in the pool.\n function isOperatorInPool(address operator) public view returns (bool) {\n return getFlaggedLeafPosition(operator) != 0;\n }\n\n /// @notice Return whether the operator's weight in the pool\n /// matches their eligible weight.\n function isOperatorUpToDate(address operator, uint256 authorizedStake)\n public\n view\n returns (bool)\n {\n return getWeight(authorizedStake) == getPoolWeight(operator);\n }\n\n /// @notice Return the weight of the operator in the pool,\n /// which may or may not be out of date.\n function getPoolWeight(address operator) public view returns (uint256) {\n uint256 flaggedPosition = getFlaggedLeafPosition(operator);\n if (flaggedPosition == 0) {\n return 0;\n } else {\n uint256 leafPosition = flaggedPosition.unsetFlag();\n uint256 leafWeight = getLeafWeight(leafPosition);\n return leafWeight;\n }\n }\n\n /// @notice Selects a new group of operators of the provided size based on\n /// the provided pseudo-random seed. At least one operator has to be\n /// registered in the pool, otherwise the function fails reverting the\n /// transaction.\n /// @param groupSize Size of the requested group\n /// @param seed Pseudo-random number used to select operators to group\n /// @return selected Members of the selected group\n function selectGroup(uint256 groupSize, bytes32 seed)\n public\n view\n onlyLocked\n returns (uint32[] memory)\n {\n uint256 _root = root;\n\n bytes32 rngState = seed;\n uint256 rngRange = _root.sumWeight();\n require(rngRange > 0, \"Not enough operators in pool\");\n uint256 currentIndex;\n\n uint256 bits = RNG.bitsRequired(rngRange);\n\n uint32[] memory selected = new uint32[](groupSize);\n\n for (uint256 i = 0; i < groupSize; i++) {\n (currentIndex, rngState) = RNG.getIndex(rngRange, rngState, bits);\n\n uint256 leafPosition = pickWeightedLeaf(currentIndex, _root);\n\n uint256 leaf = leaves[leafPosition];\n selected[i] = leaf.id();\n }\n return selected;\n }\n\n function getWeight(uint256 authorization) internal view returns (uint256) {\n return authorization / poolWeightDivisor;\n }\n}\n" + }, + "@keep-network/sortition-pools/contracts/SortitionTree.sol": { + "content": "pragma solidity 0.8.17;\n\nimport \"./Branch.sol\";\nimport \"./Position.sol\";\nimport \"./Leaf.sol\";\nimport \"./Constants.sol\";\n\ncontract SortitionTree {\n using Branch for uint256;\n using Position for uint256;\n using Leaf for uint256;\n\n // implicit tree\n // root 8\n // level2 64\n // level3 512\n // level4 4k\n // level5 32k\n // level6 256k\n // level7 2M\n uint256 internal root;\n\n // A 2-index mapping from layer => (index (0-index) => branch). For example,\n // to access the 6th branch in the 2nd layer (right below the root node; the\n // first branch layer), call branches[2][5]. Mappings are used in place of\n // arrays for efficiency. The root is the first layer, the branches occupy\n // layers 2 through 7, and layer 8 is for the leaves. Following this\n // convention, the first index in `branches` is `2`, and the last index is\n // `7`.\n mapping(uint256 => mapping(uint256 => uint256)) internal branches;\n\n // A 0-index mapping from index => leaf, acting as an array. For example, to\n // access the 42nd leaf, call leaves[41].\n mapping(uint256 => uint256) internal leaves;\n\n // the flagged (see setFlag() and unsetFlag() in Position.sol) positions\n // of all operators present in the pool\n mapping(address => uint256) internal flaggedLeafPosition;\n\n // the leaf after the rightmost occupied leaf of each stack\n uint256 internal rightmostLeaf;\n\n // the empty leaves in each stack\n // between 0 and the rightmost occupied leaf\n uint256[] internal emptyLeaves;\n\n // Each operator has an uint32 ID number\n // which is allocated when they first join the pool\n // and remains unchanged even if they leave and rejoin the pool.\n mapping(address => uint32) internal operatorID;\n\n // The idAddress array records the address corresponding to each ID number.\n // The ID number 0 is initialized with a zero address and is not used.\n address[] internal idAddress;\n\n constructor() {\n root = 0;\n rightmostLeaf = 0;\n idAddress.push();\n }\n\n /// @notice Return the ID number of the given operator address. An ID number\n /// of 0 means the operator has not been allocated an ID number yet.\n /// @param operator Address of the operator.\n /// @return the ID number of the given operator address\n function getOperatorID(address operator) public view returns (uint32) {\n return operatorID[operator];\n }\n\n /// @notice Get the operator address corresponding to the given ID number. A\n /// zero address means the ID number has not been allocated yet.\n /// @param id ID of the operator\n /// @return the address of the operator\n function getIDOperator(uint32 id) public view returns (address) {\n return idAddress.length > id ? idAddress[id] : address(0);\n }\n\n /// @notice Gets the operator addresses corresponding to the given ID\n /// numbers. A zero address means the ID number has not been allocated yet.\n /// This function works just like getIDOperator except that it allows to fetch\n /// operator addresses for multiple IDs in one call.\n /// @param ids the array of the operator ids\n /// @return an array of the associated operator addresses\n function getIDOperators(uint32[] calldata ids)\n public\n view\n returns (address[] memory)\n {\n uint256 idCount = idAddress.length;\n\n address[] memory operators = new address[](ids.length);\n for (uint256 i = 0; i < ids.length; i++) {\n uint32 id = ids[i];\n operators[i] = idCount > id ? idAddress[id] : address(0);\n }\n return operators;\n }\n\n /// @notice Checks if operator is already registered in the pool.\n /// @param operator the address of the operator\n /// @return whether or not the operator is already registered in the pool\n function isOperatorRegistered(address operator) public view returns (bool) {\n return getFlaggedLeafPosition(operator) != 0;\n }\n\n /// @notice Sum the number of operators in each trunk.\n /// @return the number of operators in the pool\n function operatorsInPool() public view returns (uint256) {\n // Get the number of leaves that might be occupied;\n // if `rightmostLeaf` equals `firstLeaf()` the tree must be empty,\n // otherwise the difference between these numbers\n // gives the number of leaves that may be occupied.\n uint256 nPossiblyUsedLeaves = rightmostLeaf;\n // Get the number of empty leaves\n // not accounted for by the `rightmostLeaf`\n uint256 nEmptyLeaves = emptyLeaves.length;\n\n return (nPossiblyUsedLeaves - nEmptyLeaves);\n }\n\n /// @notice Convenience method to return the total weight of the pool\n /// @return the total weight of the pool\n function totalWeight() public view returns (uint256) {\n return root.sumWeight();\n }\n\n /// @notice Give the operator a new ID number.\n /// Does not check if the operator already has an ID number.\n /// @param operator the address of the operator\n /// @return a new ID for that operator\n function allocateOperatorID(address operator) internal returns (uint256) {\n uint256 id = idAddress.length;\n\n require(id <= type(uint32).max, \"Pool capacity exceeded\");\n\n operatorID[operator] = uint32(id);\n idAddress.push(operator);\n return id;\n }\n\n /// @notice Inserts an operator into the sortition pool\n /// @param operator the address of an operator to insert\n /// @param weight how much weight that operator has in the pool\n function _insertOperator(address operator, uint256 weight) internal {\n require(\n !isOperatorRegistered(operator),\n \"Operator is already registered in the pool\"\n );\n\n // Fetch the operator's ID, and if they don't have one, allocate them one.\n uint256 id = getOperatorID(operator);\n if (id == 0) {\n id = allocateOperatorID(operator);\n }\n\n // Determine which leaf to insert them into\n uint256 position = getEmptyLeafPosition();\n // Record the block the operator was inserted in\n uint256 theLeaf = Leaf.make(operator, block.number, id);\n\n // Update the leaf, and propagate the weight changes all the way up to the\n // root.\n root = setLeaf(position, theLeaf, weight, root);\n\n // Without position flags,\n // the position 0x000000 would be treated as empty\n flaggedLeafPosition[operator] = position.setFlag();\n }\n\n /// @notice Remove an operator (and their weight) from the pool.\n /// @param operator the address of the operator to remove\n function _removeOperator(address operator) internal {\n uint256 flaggedPosition = getFlaggedLeafPosition(operator);\n require(flaggedPosition != 0, \"Operator is not registered in the pool\");\n uint256 unflaggedPosition = flaggedPosition.unsetFlag();\n\n // Update the leaf, and propagate the weight changes all the way up to the\n // root.\n root = removeLeaf(unflaggedPosition, root);\n removeLeafPositionRecord(operator);\n }\n\n /// @notice Update an operator's weight in the pool.\n /// @param operator the address of the operator to update\n /// @param weight the new weight\n function updateOperator(address operator, uint256 weight) internal {\n require(\n isOperatorRegistered(operator),\n \"Operator is not registered in the pool\"\n );\n\n uint256 flaggedPosition = getFlaggedLeafPosition(operator);\n uint256 unflaggedPosition = flaggedPosition.unsetFlag();\n root = updateLeaf(unflaggedPosition, weight, root);\n }\n\n /// @notice Helper method to remove a leaf position record for an operator.\n /// @param operator the address of the operator to remove the record for\n function removeLeafPositionRecord(address operator) internal {\n flaggedLeafPosition[operator] = 0;\n }\n\n /// @notice Removes the data and weight from a particular leaf.\n /// @param position the leaf index to remove\n /// @param _root the root node containing the leaf\n /// @return the updated root node\n function removeLeaf(uint256 position, uint256 _root)\n internal\n returns (uint256)\n {\n uint256 rightmostSubOne = rightmostLeaf - 1;\n bool isRightmost = position == rightmostSubOne;\n\n // Clears out the data in the leaf node, and then propagates the weight\n // changes all the way up to the root.\n uint256 newRoot = setLeaf(position, 0, 0, _root);\n\n // Infer if need to fall back on emptyLeaves yet\n if (isRightmost) {\n rightmostLeaf = rightmostSubOne;\n } else {\n emptyLeaves.push(position);\n }\n return newRoot;\n }\n\n /// @notice Updates the tree to give a particular leaf a new weight.\n /// @param position the index of the leaf to update\n /// @param weight the new weight\n /// @param _root the root node containing the leaf\n /// @return the updated root node\n function updateLeaf(\n uint256 position,\n uint256 weight,\n uint256 _root\n ) internal returns (uint256) {\n if (getLeafWeight(position) != weight) {\n return updateTree(position, weight, _root);\n } else {\n return _root;\n }\n }\n\n /// @notice Places a leaf into a particular position, with a given weight and\n /// propagates that change.\n /// @param position the index to place the leaf in\n /// @param theLeaf the new leaf to place in the position\n /// @param leafWeight the weight of the leaf\n /// @param _root the root containing the new leaf\n /// @return the updated root node\n function setLeaf(\n uint256 position,\n uint256 theLeaf,\n uint256 leafWeight,\n uint256 _root\n ) internal returns (uint256) {\n // set leaf\n leaves[position] = theLeaf;\n\n return (updateTree(position, leafWeight, _root));\n }\n\n /// @notice Propagates a weight change at a position through the tree,\n /// eventually returning the updated root.\n /// @param position the index of leaf to update\n /// @param weight the new weight of the leaf\n /// @param _root the root node containing the leaf\n /// @return the updated root node\n function updateTree(\n uint256 position,\n uint256 weight,\n uint256 _root\n ) internal returns (uint256) {\n uint256 childSlot;\n uint256 treeNode;\n uint256 newNode;\n uint256 nodeWeight = weight;\n\n uint256 parent = position;\n // set levels 7 to 2\n for (uint256 level = Constants.LEVELS; level >= 2; level--) {\n childSlot = parent.slot();\n parent = parent.parent();\n treeNode = branches[level][parent];\n newNode = treeNode.setSlot(childSlot, nodeWeight);\n branches[level][parent] = newNode;\n nodeWeight = newNode.sumWeight();\n }\n\n // set level Root\n childSlot = parent.slot();\n return _root.setSlot(childSlot, nodeWeight);\n }\n\n /// @notice Retrieves the next available empty leaf position. Tries to fill\n /// left to right first, ignoring leaf removals, and then fills\n /// most-recent-removals first.\n /// @return the position of the empty leaf\n function getEmptyLeafPosition() internal returns (uint256) {\n uint256 rLeaf = rightmostLeaf;\n bool spaceOnRight = (rLeaf + 1) < Constants.POOL_CAPACITY;\n if (spaceOnRight) {\n rightmostLeaf = rLeaf + 1;\n return rLeaf;\n } else {\n uint256 emptyLeafCount = emptyLeaves.length;\n require(emptyLeafCount > 0, \"Pool is full\");\n uint256 emptyLeaf = emptyLeaves[emptyLeafCount - 1];\n emptyLeaves.pop();\n return emptyLeaf;\n }\n }\n\n /// @notice Gets the flagged leaf position for an operator.\n /// @param operator the address of the operator\n /// @return the leaf position of that operator\n function getFlaggedLeafPosition(address operator)\n internal\n view\n returns (uint256)\n {\n return flaggedLeafPosition[operator];\n }\n\n /// @notice Gets the weight of a leaf at a particular position.\n /// @param position the index of the leaf\n /// @return the weight of the leaf at that position\n function getLeafWeight(uint256 position) internal view returns (uint256) {\n uint256 slot = position.slot();\n uint256 parent = position.parent();\n\n // A leaf's weight information is stored a 32-bit slot in the branch layer\n // directly above the leaf layer. To access it, we calculate that slot and\n // parent position, and always know the hard-coded layer index.\n uint256 node = branches[Constants.LEVELS][parent];\n return node.getSlot(slot);\n }\n\n /// @notice Picks a leaf given a random index.\n /// @param index a number in `[0, _root.totalWeight())` used to decide\n /// between leaves\n /// @param _root the root of the tree\n function pickWeightedLeaf(uint256 index, uint256 _root)\n internal\n view\n returns (uint256 leafPosition)\n {\n uint256 currentIndex = index;\n uint256 currentNode = _root;\n uint256 currentPosition = 0;\n uint256 currentSlot;\n\n require(index < currentNode.sumWeight(), \"Index exceeds weight\");\n\n // get root slot\n (currentSlot, currentIndex) = currentNode.pickWeightedSlot(currentIndex);\n\n // get slots from levels 2 to 7\n for (uint256 level = 2; level <= Constants.LEVELS; level++) {\n currentPosition = currentPosition.child(currentSlot);\n currentNode = branches[level][currentPosition];\n (currentSlot, currentIndex) = currentNode.pickWeightedSlot(currentIndex);\n }\n\n // get leaf position\n leafPosition = currentPosition.child(currentSlot);\n }\n}\n" + }, + "@openzeppelin/contracts-upgradeable/access/OwnableUpgradeable.sol": { + "content": "// SPDX-License-Identifier: MIT\n// OpenZeppelin Contracts (last updated v4.7.0) (access/Ownable.sol)\n\npragma solidity ^0.8.0;\n\nimport \"../utils/ContextUpgradeable.sol\";\nimport \"../proxy/utils/Initializable.sol\";\n\n/**\n * @dev Contract module which provides a basic access control mechanism, where\n * there is an account (an owner) that can be granted exclusive access to\n * specific functions.\n *\n * By default, the owner account will be the one that deploys the contract. This\n * can later be changed with {transferOwnership}.\n *\n * This module is used through inheritance. It will make available the modifier\n * `onlyOwner`, which can be applied to your functions to restrict their use to\n * the owner.\n */\nabstract contract OwnableUpgradeable is Initializable, ContextUpgradeable {\n address private _owner;\n\n event OwnershipTransferred(address indexed previousOwner, address indexed newOwner);\n\n /**\n * @dev Initializes the contract setting the deployer as the initial owner.\n */\n function __Ownable_init() internal onlyInitializing {\n __Ownable_init_unchained();\n }\n\n function __Ownable_init_unchained() internal onlyInitializing {\n _transferOwnership(_msgSender());\n }\n\n /**\n * @dev Throws if called by any account other than the owner.\n */\n modifier onlyOwner() {\n _checkOwner();\n _;\n }\n\n /**\n * @dev Returns the address of the current owner.\n */\n function owner() public view virtual returns (address) {\n return _owner;\n }\n\n /**\n * @dev Throws if the sender is not the owner.\n */\n function _checkOwner() internal view virtual {\n require(owner() == _msgSender(), \"Ownable: caller is not the owner\");\n }\n\n /**\n * @dev Leaves the contract without owner. It will not be possible to call\n * `onlyOwner` functions anymore. Can only be called by the current owner.\n *\n * NOTE: Renouncing ownership will leave the contract without an owner,\n * thereby removing any functionality that is only available to the owner.\n */\n function renounceOwnership() public virtual onlyOwner {\n _transferOwnership(address(0));\n }\n\n /**\n * @dev Transfers ownership of the contract to a new account (`newOwner`).\n * Can only be called by the current owner.\n */\n function transferOwnership(address newOwner) public virtual onlyOwner {\n require(newOwner != address(0), \"Ownable: new owner is the zero address\");\n _transferOwnership(newOwner);\n }\n\n /**\n * @dev Transfers ownership of the contract to a new account (`newOwner`).\n * Internal function without access restriction.\n */\n function _transferOwnership(address newOwner) internal virtual {\n address oldOwner = _owner;\n _owner = newOwner;\n emit OwnershipTransferred(oldOwner, newOwner);\n }\n\n /**\n * @dev This empty reserved space is put in place to allow future versions to add new\n * variables without shifting down storage in the inheritance chain.\n * See https://docs.openzeppelin.com/contracts/4.x/upgradeable#storage_gaps\n */\n uint256[49] private __gap;\n}\n" + }, + "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol": { + "content": "// SPDX-License-Identifier: MIT\n// OpenZeppelin Contracts (last updated v4.8.1) (proxy/utils/Initializable.sol)\n\npragma solidity ^0.8.2;\n\nimport \"../../utils/AddressUpgradeable.sol\";\n\n/**\n * @dev This is a base contract to aid in writing upgradeable contracts, or any kind of contract that will be deployed\n * behind a proxy. Since proxied contracts do not make use of a constructor, it's common to move constructor logic to an\n * external initializer function, usually called `initialize`. It then becomes necessary to protect this initializer\n * function so it can only be called once. The {initializer} modifier provided by this contract will have this effect.\n *\n * The initialization functions use a version number. Once a version number is used, it is consumed and cannot be\n * reused. This mechanism prevents re-execution of each \"step\" but allows the creation of new initialization steps in\n * case an upgrade adds a module that needs to be initialized.\n *\n * For example:\n *\n * [.hljs-theme-light.nopadding]\n * ```\n * contract MyToken is ERC20Upgradeable {\n * function initialize() initializer public {\n * __ERC20_init(\"MyToken\", \"MTK\");\n * }\n * }\n * contract MyTokenV2 is MyToken, ERC20PermitUpgradeable {\n * function initializeV2() reinitializer(2) public {\n * __ERC20Permit_init(\"MyToken\");\n * }\n * }\n * ```\n *\n * TIP: To avoid leaving the proxy in an uninitialized state, the initializer function should be called as early as\n * possible by providing the encoded function call as the `_data` argument to {ERC1967Proxy-constructor}.\n *\n * CAUTION: When used with inheritance, manual care must be taken to not invoke a parent initializer twice, or to ensure\n * that all initializers are idempotent. This is not verified automatically as constructors are by Solidity.\n *\n * [CAUTION]\n * ====\n * Avoid leaving a contract uninitialized.\n *\n * An uninitialized contract can be taken over by an attacker. This applies to both a proxy and its implementation\n * contract, which may impact the proxy. To prevent the implementation contract from being used, you should invoke\n * the {_disableInitializers} function in the constructor to automatically lock it when it is deployed:\n *\n * [.hljs-theme-light.nopadding]\n * ```\n * /// @custom:oz-upgrades-unsafe-allow constructor\n * constructor() {\n * _disableInitializers();\n * }\n * ```\n * ====\n */\nabstract contract Initializable {\n /**\n * @dev Indicates that the contract has been initialized.\n * @custom:oz-retyped-from bool\n */\n uint8 private _initialized;\n\n /**\n * @dev Indicates that the contract is in the process of being initialized.\n */\n bool private _initializing;\n\n /**\n * @dev Triggered when the contract has been initialized or reinitialized.\n */\n event Initialized(uint8 version);\n\n /**\n * @dev A modifier that defines a protected initializer function that can be invoked at most once. In its scope,\n * `onlyInitializing` functions can be used to initialize parent contracts.\n *\n * Similar to `reinitializer(1)`, except that functions marked with `initializer` can be nested in the context of a\n * constructor.\n *\n * Emits an {Initialized} event.\n */\n modifier initializer() {\n bool isTopLevelCall = !_initializing;\n require(\n (isTopLevelCall && _initialized < 1) || (!AddressUpgradeable.isContract(address(this)) && _initialized == 1),\n \"Initializable: contract is already initialized\"\n );\n _initialized = 1;\n if (isTopLevelCall) {\n _initializing = true;\n }\n _;\n if (isTopLevelCall) {\n _initializing = false;\n emit Initialized(1);\n }\n }\n\n /**\n * @dev A modifier that defines a protected reinitializer function that can be invoked at most once, and only if the\n * contract hasn't been initialized to a greater version before. In its scope, `onlyInitializing` functions can be\n * used to initialize parent contracts.\n *\n * A reinitializer may be used after the original initialization step. This is essential to configure modules that\n * are added through upgrades and that require initialization.\n *\n * When `version` is 1, this modifier is similar to `initializer`, except that functions marked with `reinitializer`\n * cannot be nested. If one is invoked in the context of another, execution will revert.\n *\n * Note that versions can jump in increments greater than 1; this implies that if multiple reinitializers coexist in\n * a contract, executing them in the right order is up to the developer or operator.\n *\n * WARNING: setting the version to 255 will prevent any future reinitialization.\n *\n * Emits an {Initialized} event.\n */\n modifier reinitializer(uint8 version) {\n require(!_initializing && _initialized < version, \"Initializable: contract is already initialized\");\n _initialized = version;\n _initializing = true;\n _;\n _initializing = false;\n emit Initialized(version);\n }\n\n /**\n * @dev Modifier to protect an initialization function so that it can only be invoked by functions with the\n * {initializer} and {reinitializer} modifiers, directly or indirectly.\n */\n modifier onlyInitializing() {\n require(_initializing, \"Initializable: contract is not initializing\");\n _;\n }\n\n /**\n * @dev Locks the contract, preventing any future reinitialization. This cannot be part of an initializer call.\n * Calling this in the constructor of a contract will prevent that contract from being initialized or reinitialized\n * to any version. It is recommended to use this to lock implementation contracts that are designed to be called\n * through proxies.\n *\n * Emits an {Initialized} event the first time it is successfully executed.\n */\n function _disableInitializers() internal virtual {\n require(!_initializing, \"Initializable: contract is initializing\");\n if (_initialized < type(uint8).max) {\n _initialized = type(uint8).max;\n emit Initialized(type(uint8).max);\n }\n }\n\n /**\n * @dev Returns the highest version that has been initialized. See {reinitializer}.\n */\n function _getInitializedVersion() internal view returns (uint8) {\n return _initialized;\n }\n\n /**\n * @dev Returns `true` if the contract is currently initializing. See {onlyInitializing}.\n */\n function _isInitializing() internal view returns (bool) {\n return _initializing;\n }\n}\n" + }, + "@openzeppelin/contracts-upgradeable/security/PausableUpgradeable.sol": { + "content": "// SPDX-License-Identifier: MIT\n// OpenZeppelin Contracts (last updated v4.7.0) (security/Pausable.sol)\n\npragma solidity ^0.8.0;\n\nimport \"../utils/ContextUpgradeable.sol\";\nimport \"../proxy/utils/Initializable.sol\";\n\n/**\n * @dev Contract module which allows children to implement an emergency stop\n * mechanism that can be triggered by an authorized account.\n *\n * This module is used through inheritance. It will make available the\n * modifiers `whenNotPaused` and `whenPaused`, which can be applied to\n * the functions of your contract. Note that they will not be pausable by\n * simply including this module, only once the modifiers are put in place.\n */\nabstract contract PausableUpgradeable is Initializable, ContextUpgradeable {\n /**\n * @dev Emitted when the pause is triggered by `account`.\n */\n event Paused(address account);\n\n /**\n * @dev Emitted when the pause is lifted by `account`.\n */\n event Unpaused(address account);\n\n bool private _paused;\n\n /**\n * @dev Initializes the contract in unpaused state.\n */\n function __Pausable_init() internal onlyInitializing {\n __Pausable_init_unchained();\n }\n\n function __Pausable_init_unchained() internal onlyInitializing {\n _paused = false;\n }\n\n /**\n * @dev Modifier to make a function callable only when the contract is not paused.\n *\n * Requirements:\n *\n * - The contract must not be paused.\n */\n modifier whenNotPaused() {\n _requireNotPaused();\n _;\n }\n\n /**\n * @dev Modifier to make a function callable only when the contract is paused.\n *\n * Requirements:\n *\n * - The contract must be paused.\n */\n modifier whenPaused() {\n _requirePaused();\n _;\n }\n\n /**\n * @dev Returns true if the contract is paused, and false otherwise.\n */\n function paused() public view virtual returns (bool) {\n return _paused;\n }\n\n /**\n * @dev Throws if the contract is paused.\n */\n function _requireNotPaused() internal view virtual {\n require(!paused(), \"Pausable: paused\");\n }\n\n /**\n * @dev Throws if the contract is not paused.\n */\n function _requirePaused() internal view virtual {\n require(paused(), \"Pausable: not paused\");\n }\n\n /**\n * @dev Triggers stopped state.\n *\n * Requirements:\n *\n * - The contract must not be paused.\n */\n function _pause() internal virtual whenNotPaused {\n _paused = true;\n emit Paused(_msgSender());\n }\n\n /**\n * @dev Returns to normal state.\n *\n * Requirements:\n *\n * - The contract must be paused.\n */\n function _unpause() internal virtual whenPaused {\n _paused = false;\n emit Unpaused(_msgSender());\n }\n\n /**\n * @dev This empty reserved space is put in place to allow future versions to add new\n * variables without shifting down storage in the inheritance chain.\n * See https://docs.openzeppelin.com/contracts/4.x/upgradeable#storage_gaps\n */\n uint256[49] private __gap;\n}\n" + }, + "@openzeppelin/contracts-upgradeable/security/ReentrancyGuardUpgradeable.sol": { + "content": "// SPDX-License-Identifier: MIT\n// OpenZeppelin Contracts (last updated v4.8.0) (security/ReentrancyGuard.sol)\n\npragma solidity ^0.8.0;\nimport \"../proxy/utils/Initializable.sol\";\n\n/**\n * @dev Contract module that helps prevent reentrant calls to a function.\n *\n * Inheriting from `ReentrancyGuard` will make the {nonReentrant} modifier\n * available, which can be applied to functions to make sure there are no nested\n * (reentrant) calls to them.\n *\n * Note that because there is a single `nonReentrant` guard, functions marked as\n * `nonReentrant` may not call one another. This can be worked around by making\n * those functions `private`, and then adding `external` `nonReentrant` entry\n * points to them.\n *\n * TIP: If you would like to learn more about reentrancy and alternative ways\n * to protect against it, check out our blog post\n * https://blog.openzeppelin.com/reentrancy-after-istanbul/[Reentrancy After Istanbul].\n */\nabstract contract ReentrancyGuardUpgradeable is Initializable {\n // Booleans are more expensive than uint256 or any type that takes up a full\n // word because each write operation emits an extra SLOAD to first read the\n // slot's contents, replace the bits taken up by the boolean, and then write\n // back. This is the compiler's defense against contract upgrades and\n // pointer aliasing, and it cannot be disabled.\n\n // The values being non-zero value makes deployment a bit more expensive,\n // but in exchange the refund on every call to nonReentrant will be lower in\n // amount. Since refunds are capped to a percentage of the total\n // transaction's gas, it is best to keep them low in cases like this one, to\n // increase the likelihood of the full refund coming into effect.\n uint256 private constant _NOT_ENTERED = 1;\n uint256 private constant _ENTERED = 2;\n\n uint256 private _status;\n\n function __ReentrancyGuard_init() internal onlyInitializing {\n __ReentrancyGuard_init_unchained();\n }\n\n function __ReentrancyGuard_init_unchained() internal onlyInitializing {\n _status = _NOT_ENTERED;\n }\n\n /**\n * @dev Prevents a contract from calling itself, directly or indirectly.\n * Calling a `nonReentrant` function from another `nonReentrant`\n * function is not supported. It is possible to prevent this from happening\n * by making the `nonReentrant` function external, and making it call a\n * `private` function that does the actual work.\n */\n modifier nonReentrant() {\n _nonReentrantBefore();\n _;\n _nonReentrantAfter();\n }\n\n function _nonReentrantBefore() private {\n // On the first call to nonReentrant, _status will be _NOT_ENTERED\n require(_status != _ENTERED, \"ReentrancyGuard: reentrant call\");\n\n // Any calls to nonReentrant after this point will fail\n _status = _ENTERED;\n }\n\n function _nonReentrantAfter() private {\n // By storing the original value once again, a refund is triggered (see\n // https://eips.ethereum.org/EIPS/eip-2200)\n _status = _NOT_ENTERED;\n }\n\n /**\n * @dev This empty reserved space is put in place to allow future versions to add new\n * variables without shifting down storage in the inheritance chain.\n * See https://docs.openzeppelin.com/contracts/4.x/upgradeable#storage_gaps\n */\n uint256[49] private __gap;\n}\n" + }, + "@openzeppelin/contracts-upgradeable/token/ERC20/ERC20Upgradeable.sol": { + "content": "// SPDX-License-Identifier: MIT\n// OpenZeppelin Contracts (last updated v4.8.0) (token/ERC20/ERC20.sol)\n\npragma solidity ^0.8.0;\n\nimport \"./IERC20Upgradeable.sol\";\nimport \"./extensions/IERC20MetadataUpgradeable.sol\";\nimport \"../../utils/ContextUpgradeable.sol\";\nimport \"../../proxy/utils/Initializable.sol\";\n\n/**\n * @dev Implementation of the {IERC20} interface.\n *\n * This implementation is agnostic to the way tokens are created. This means\n * that a supply mechanism has to be added in a derived contract using {_mint}.\n * For a generic mechanism see {ERC20PresetMinterPauser}.\n *\n * TIP: For a detailed writeup see our guide\n * https://forum.openzeppelin.com/t/how-to-implement-erc20-supply-mechanisms/226[How\n * to implement supply mechanisms].\n *\n * We have followed general OpenZeppelin Contracts guidelines: functions revert\n * instead returning `false` on failure. This behavior is nonetheless\n * conventional and does not conflict with the expectations of ERC20\n * applications.\n *\n * Additionally, an {Approval} event is emitted on calls to {transferFrom}.\n * This allows applications to reconstruct the allowance for all accounts just\n * by listening to said events. Other implementations of the EIP may not emit\n * these events, as it isn't required by the specification.\n *\n * Finally, the non-standard {decreaseAllowance} and {increaseAllowance}\n * functions have been added to mitigate the well-known issues around setting\n * allowances. See {IERC20-approve}.\n */\ncontract ERC20Upgradeable is Initializable, ContextUpgradeable, IERC20Upgradeable, IERC20MetadataUpgradeable {\n mapping(address => uint256) private _balances;\n\n mapping(address => mapping(address => uint256)) private _allowances;\n\n uint256 private _totalSupply;\n\n string private _name;\n string private _symbol;\n\n /**\n * @dev Sets the values for {name} and {symbol}.\n *\n * The default value of {decimals} is 18. To select a different value for\n * {decimals} you should overload it.\n *\n * All two of these values are immutable: they can only be set once during\n * construction.\n */\n function __ERC20_init(string memory name_, string memory symbol_) internal onlyInitializing {\n __ERC20_init_unchained(name_, symbol_);\n }\n\n function __ERC20_init_unchained(string memory name_, string memory symbol_) internal onlyInitializing {\n _name = name_;\n _symbol = symbol_;\n }\n\n /**\n * @dev Returns the name of the token.\n */\n function name() public view virtual override returns (string memory) {\n return _name;\n }\n\n /**\n * @dev Returns the symbol of the token, usually a shorter version of the\n * name.\n */\n function symbol() public view virtual override returns (string memory) {\n return _symbol;\n }\n\n /**\n * @dev Returns the number of decimals used to get its user representation.\n * For example, if `decimals` equals `2`, a balance of `505` tokens should\n * be displayed to a user as `5.05` (`505 / 10 ** 2`).\n *\n * Tokens usually opt for a value of 18, imitating the relationship between\n * Ether and Wei. This is the value {ERC20} uses, unless this function is\n * overridden;\n *\n * NOTE: This information is only used for _display_ purposes: it in\n * no way affects any of the arithmetic of the contract, including\n * {IERC20-balanceOf} and {IERC20-transfer}.\n */\n function decimals() public view virtual override returns (uint8) {\n return 18;\n }\n\n /**\n * @dev See {IERC20-totalSupply}.\n */\n function totalSupply() public view virtual override returns (uint256) {\n return _totalSupply;\n }\n\n /**\n * @dev See {IERC20-balanceOf}.\n */\n function balanceOf(address account) public view virtual override returns (uint256) {\n return _balances[account];\n }\n\n /**\n * @dev See {IERC20-transfer}.\n *\n * Requirements:\n *\n * - `to` cannot be the zero address.\n * - the caller must have a balance of at least `amount`.\n */\n function transfer(address to, uint256 amount) public virtual override returns (bool) {\n address owner = _msgSender();\n _transfer(owner, to, amount);\n return true;\n }\n\n /**\n * @dev See {IERC20-allowance}.\n */\n function allowance(address owner, address spender) public view virtual override returns (uint256) {\n return _allowances[owner][spender];\n }\n\n /**\n * @dev See {IERC20-approve}.\n *\n * NOTE: If `amount` is the maximum `uint256`, the allowance is not updated on\n * `transferFrom`. This is semantically equivalent to an infinite approval.\n *\n * Requirements:\n *\n * - `spender` cannot be the zero address.\n */\n function approve(address spender, uint256 amount) public virtual override returns (bool) {\n address owner = _msgSender();\n _approve(owner, spender, amount);\n return true;\n }\n\n /**\n * @dev See {IERC20-transferFrom}.\n *\n * Emits an {Approval} event indicating the updated allowance. This is not\n * required by the EIP. See the note at the beginning of {ERC20}.\n *\n * NOTE: Does not update the allowance if the current allowance\n * is the maximum `uint256`.\n *\n * Requirements:\n *\n * - `from` and `to` cannot be the zero address.\n * - `from` must have a balance of at least `amount`.\n * - the caller must have allowance for ``from``'s tokens of at least\n * `amount`.\n */\n function transferFrom(\n address from,\n address to,\n uint256 amount\n ) public virtual override returns (bool) {\n address spender = _msgSender();\n _spendAllowance(from, spender, amount);\n _transfer(from, to, amount);\n return true;\n }\n\n /**\n * @dev Atomically increases the allowance granted to `spender` by the caller.\n *\n * This is an alternative to {approve} that can be used as a mitigation for\n * problems described in {IERC20-approve}.\n *\n * Emits an {Approval} event indicating the updated allowance.\n *\n * Requirements:\n *\n * - `spender` cannot be the zero address.\n */\n function increaseAllowance(address spender, uint256 addedValue) public virtual returns (bool) {\n address owner = _msgSender();\n _approve(owner, spender, allowance(owner, spender) + addedValue);\n return true;\n }\n\n /**\n * @dev Atomically decreases the allowance granted to `spender` by the caller.\n *\n * This is an alternative to {approve} that can be used as a mitigation for\n * problems described in {IERC20-approve}.\n *\n * Emits an {Approval} event indicating the updated allowance.\n *\n * Requirements:\n *\n * - `spender` cannot be the zero address.\n * - `spender` must have allowance for the caller of at least\n * `subtractedValue`.\n */\n function decreaseAllowance(address spender, uint256 subtractedValue) public virtual returns (bool) {\n address owner = _msgSender();\n uint256 currentAllowance = allowance(owner, spender);\n require(currentAllowance >= subtractedValue, \"ERC20: decreased allowance below zero\");\n unchecked {\n _approve(owner, spender, currentAllowance - subtractedValue);\n }\n\n return true;\n }\n\n /**\n * @dev Moves `amount` of tokens from `from` to `to`.\n *\n * This internal function is equivalent to {transfer}, and can be used to\n * e.g. implement automatic token fees, slashing mechanisms, etc.\n *\n * Emits a {Transfer} event.\n *\n * Requirements:\n *\n * - `from` cannot be the zero address.\n * - `to` cannot be the zero address.\n * - `from` must have a balance of at least `amount`.\n */\n function _transfer(\n address from,\n address to,\n uint256 amount\n ) internal virtual {\n require(from != address(0), \"ERC20: transfer from the zero address\");\n require(to != address(0), \"ERC20: transfer to the zero address\");\n\n _beforeTokenTransfer(from, to, amount);\n\n uint256 fromBalance = _balances[from];\n require(fromBalance >= amount, \"ERC20: transfer amount exceeds balance\");\n unchecked {\n _balances[from] = fromBalance - amount;\n // Overflow not possible: the sum of all balances is capped by totalSupply, and the sum is preserved by\n // decrementing then incrementing.\n _balances[to] += amount;\n }\n\n emit Transfer(from, to, amount);\n\n _afterTokenTransfer(from, to, amount);\n }\n\n /** @dev Creates `amount` tokens and assigns them to `account`, increasing\n * the total supply.\n *\n * Emits a {Transfer} event with `from` set to the zero address.\n *\n * Requirements:\n *\n * - `account` cannot be the zero address.\n */\n function _mint(address account, uint256 amount) internal virtual {\n require(account != address(0), \"ERC20: mint to the zero address\");\n\n _beforeTokenTransfer(address(0), account, amount);\n\n _totalSupply += amount;\n unchecked {\n // Overflow not possible: balance + amount is at most totalSupply + amount, which is checked above.\n _balances[account] += amount;\n }\n emit Transfer(address(0), account, amount);\n\n _afterTokenTransfer(address(0), account, amount);\n }\n\n /**\n * @dev Destroys `amount` tokens from `account`, reducing the\n * total supply.\n *\n * Emits a {Transfer} event with `to` set to the zero address.\n *\n * Requirements:\n *\n * - `account` cannot be the zero address.\n * - `account` must have at least `amount` tokens.\n */\n function _burn(address account, uint256 amount) internal virtual {\n require(account != address(0), \"ERC20: burn from the zero address\");\n\n _beforeTokenTransfer(account, address(0), amount);\n\n uint256 accountBalance = _balances[account];\n require(accountBalance >= amount, \"ERC20: burn amount exceeds balance\");\n unchecked {\n _balances[account] = accountBalance - amount;\n // Overflow not possible: amount <= accountBalance <= totalSupply.\n _totalSupply -= amount;\n }\n\n emit Transfer(account, address(0), amount);\n\n _afterTokenTransfer(account, address(0), amount);\n }\n\n /**\n * @dev Sets `amount` as the allowance of `spender` over the `owner` s tokens.\n *\n * This internal function is equivalent to `approve`, and can be used to\n * e.g. set automatic allowances for certain subsystems, etc.\n *\n * Emits an {Approval} event.\n *\n * Requirements:\n *\n * - `owner` cannot be the zero address.\n * - `spender` cannot be the zero address.\n */\n function _approve(\n address owner,\n address spender,\n uint256 amount\n ) internal virtual {\n require(owner != address(0), \"ERC20: approve from the zero address\");\n require(spender != address(0), \"ERC20: approve to the zero address\");\n\n _allowances[owner][spender] = amount;\n emit Approval(owner, spender, amount);\n }\n\n /**\n * @dev Updates `owner` s allowance for `spender` based on spent `amount`.\n *\n * Does not update the allowance amount in case of infinite allowance.\n * Revert if not enough allowance is available.\n *\n * Might emit an {Approval} event.\n */\n function _spendAllowance(\n address owner,\n address spender,\n uint256 amount\n ) internal virtual {\n uint256 currentAllowance = allowance(owner, spender);\n if (currentAllowance != type(uint256).max) {\n require(currentAllowance >= amount, \"ERC20: insufficient allowance\");\n unchecked {\n _approve(owner, spender, currentAllowance - amount);\n }\n }\n }\n\n /**\n * @dev Hook that is called before any transfer of tokens. This includes\n * minting and burning.\n *\n * Calling conditions:\n *\n * - when `from` and `to` are both non-zero, `amount` of ``from``'s tokens\n * will be transferred to `to`.\n * - when `from` is zero, `amount` tokens will be minted for `to`.\n * - when `to` is zero, `amount` of ``from``'s tokens will be burned.\n * - `from` and `to` are never both zero.\n *\n * To learn more about hooks, head to xref:ROOT:extending-contracts.adoc#using-hooks[Using Hooks].\n */\n function _beforeTokenTransfer(\n address from,\n address to,\n uint256 amount\n ) internal virtual {}\n\n /**\n * @dev Hook that is called after any transfer of tokens. This includes\n * minting and burning.\n *\n * Calling conditions:\n *\n * - when `from` and `to` are both non-zero, `amount` of ``from``'s tokens\n * has been transferred to `to`.\n * - when `from` is zero, `amount` tokens have been minted for `to`.\n * - when `to` is zero, `amount` of ``from``'s tokens have been burned.\n * - `from` and `to` are never both zero.\n *\n * To learn more about hooks, head to xref:ROOT:extending-contracts.adoc#using-hooks[Using Hooks].\n */\n function _afterTokenTransfer(\n address from,\n address to,\n uint256 amount\n ) internal virtual {}\n\n /**\n * @dev This empty reserved space is put in place to allow future versions to add new\n * variables without shifting down storage in the inheritance chain.\n * See https://docs.openzeppelin.com/contracts/4.x/upgradeable#storage_gaps\n */\n uint256[45] private __gap;\n}\n" + }, + "@openzeppelin/contracts-upgradeable/token/ERC20/extensions/draft-ERC20PermitUpgradeable.sol": { + "content": "// SPDX-License-Identifier: MIT\n// OpenZeppelin Contracts (last updated v4.8.0) (token/ERC20/extensions/draft-ERC20Permit.sol)\n\npragma solidity ^0.8.0;\n\nimport \"./draft-IERC20PermitUpgradeable.sol\";\nimport \"../ERC20Upgradeable.sol\";\nimport \"../../../utils/cryptography/ECDSAUpgradeable.sol\";\nimport \"../../../utils/cryptography/EIP712Upgradeable.sol\";\nimport \"../../../utils/CountersUpgradeable.sol\";\nimport \"../../../proxy/utils/Initializable.sol\";\n\n/**\n * @dev Implementation of the ERC20 Permit extension allowing approvals to be made via signatures, as defined in\n * https://eips.ethereum.org/EIPS/eip-2612[EIP-2612].\n *\n * Adds the {permit} method, which can be used to change an account's ERC20 allowance (see {IERC20-allowance}) by\n * presenting a message signed by the account. By not relying on `{IERC20-approve}`, the token holder account doesn't\n * need to send a transaction, and thus is not required to hold Ether at all.\n *\n * _Available since v3.4._\n *\n * @custom:storage-size 51\n */\nabstract contract ERC20PermitUpgradeable is Initializable, ERC20Upgradeable, IERC20PermitUpgradeable, EIP712Upgradeable {\n using CountersUpgradeable for CountersUpgradeable.Counter;\n\n mapping(address => CountersUpgradeable.Counter) private _nonces;\n\n // solhint-disable-next-line var-name-mixedcase\n bytes32 private constant _PERMIT_TYPEHASH =\n keccak256(\"Permit(address owner,address spender,uint256 value,uint256 nonce,uint256 deadline)\");\n /**\n * @dev In previous versions `_PERMIT_TYPEHASH` was declared as `immutable`.\n * However, to ensure consistency with the upgradeable transpiler, we will continue\n * to reserve a slot.\n * @custom:oz-renamed-from _PERMIT_TYPEHASH\n */\n // solhint-disable-next-line var-name-mixedcase\n bytes32 private _PERMIT_TYPEHASH_DEPRECATED_SLOT;\n\n /**\n * @dev Initializes the {EIP712} domain separator using the `name` parameter, and setting `version` to `\"1\"`.\n *\n * It's a good idea to use the same `name` that is defined as the ERC20 token name.\n */\n function __ERC20Permit_init(string memory name) internal onlyInitializing {\n __EIP712_init_unchained(name, \"1\");\n }\n\n function __ERC20Permit_init_unchained(string memory) internal onlyInitializing {}\n\n /**\n * @dev See {IERC20Permit-permit}.\n */\n function permit(\n address owner,\n address spender,\n uint256 value,\n uint256 deadline,\n uint8 v,\n bytes32 r,\n bytes32 s\n ) public virtual override {\n require(block.timestamp <= deadline, \"ERC20Permit: expired deadline\");\n\n bytes32 structHash = keccak256(abi.encode(_PERMIT_TYPEHASH, owner, spender, value, _useNonce(owner), deadline));\n\n bytes32 hash = _hashTypedDataV4(structHash);\n\n address signer = ECDSAUpgradeable.recover(hash, v, r, s);\n require(signer == owner, \"ERC20Permit: invalid signature\");\n\n _approve(owner, spender, value);\n }\n\n /**\n * @dev See {IERC20Permit-nonces}.\n */\n function nonces(address owner) public view virtual override returns (uint256) {\n return _nonces[owner].current();\n }\n\n /**\n * @dev See {IERC20Permit-DOMAIN_SEPARATOR}.\n */\n // solhint-disable-next-line func-name-mixedcase\n function DOMAIN_SEPARATOR() external view override returns (bytes32) {\n return _domainSeparatorV4();\n }\n\n /**\n * @dev \"Consume a nonce\": return the current value and increment.\n *\n * _Available since v4.1._\n */\n function _useNonce(address owner) internal virtual returns (uint256 current) {\n CountersUpgradeable.Counter storage nonce = _nonces[owner];\n current = nonce.current();\n nonce.increment();\n }\n\n /**\n * @dev This empty reserved space is put in place to allow future versions to add new\n * variables without shifting down storage in the inheritance chain.\n * See https://docs.openzeppelin.com/contracts/4.x/upgradeable#storage_gaps\n */\n uint256[49] private __gap;\n}\n" + }, + "@openzeppelin/contracts-upgradeable/token/ERC20/extensions/draft-IERC20PermitUpgradeable.sol": { + "content": "// SPDX-License-Identifier: MIT\n// OpenZeppelin Contracts v4.4.1 (token/ERC20/extensions/draft-IERC20Permit.sol)\n\npragma solidity ^0.8.0;\n\n/**\n * @dev Interface of the ERC20 Permit extension allowing approvals to be made via signatures, as defined in\n * https://eips.ethereum.org/EIPS/eip-2612[EIP-2612].\n *\n * Adds the {permit} method, which can be used to change an account's ERC20 allowance (see {IERC20-allowance}) by\n * presenting a message signed by the account. By not relying on {IERC20-approve}, the token holder account doesn't\n * need to send a transaction, and thus is not required to hold Ether at all.\n */\ninterface IERC20PermitUpgradeable {\n /**\n * @dev Sets `value` as the allowance of `spender` over ``owner``'s tokens,\n * given ``owner``'s signed approval.\n *\n * IMPORTANT: The same issues {IERC20-approve} has related to transaction\n * ordering also apply here.\n *\n * Emits an {Approval} event.\n *\n * Requirements:\n *\n * - `spender` cannot be the zero address.\n * - `deadline` must be a timestamp in the future.\n * - `v`, `r` and `s` must be a valid `secp256k1` signature from `owner`\n * over the EIP712-formatted function arguments.\n * - the signature must use ``owner``'s current nonce (see {nonces}).\n *\n * For more information on the signature format, see the\n * https://eips.ethereum.org/EIPS/eip-2612#specification[relevant EIP\n * section].\n */\n function permit(\n address owner,\n address spender,\n uint256 value,\n uint256 deadline,\n uint8 v,\n bytes32 r,\n bytes32 s\n ) external;\n\n /**\n * @dev Returns the current nonce for `owner`. This value must be\n * included whenever a signature is generated for {permit}.\n *\n * Every successful call to {permit} increases ``owner``'s nonce by one. This\n * prevents a signature from being used multiple times.\n */\n function nonces(address owner) external view returns (uint256);\n\n /**\n * @dev Returns the domain separator used in the encoding of the signature for {permit}, as defined by {EIP712}.\n */\n // solhint-disable-next-line func-name-mixedcase\n function DOMAIN_SEPARATOR() external view returns (bytes32);\n}\n" + }, + "@openzeppelin/contracts-upgradeable/token/ERC20/extensions/ERC20BurnableUpgradeable.sol": { + "content": "// SPDX-License-Identifier: MIT\n// OpenZeppelin Contracts (last updated v4.5.0) (token/ERC20/extensions/ERC20Burnable.sol)\n\npragma solidity ^0.8.0;\n\nimport \"../ERC20Upgradeable.sol\";\nimport \"../../../utils/ContextUpgradeable.sol\";\nimport \"../../../proxy/utils/Initializable.sol\";\n\n/**\n * @dev Extension of {ERC20} that allows token holders to destroy both their own\n * tokens and those that they have an allowance for, in a way that can be\n * recognized off-chain (via event analysis).\n */\nabstract contract ERC20BurnableUpgradeable is Initializable, ContextUpgradeable, ERC20Upgradeable {\n function __ERC20Burnable_init() internal onlyInitializing {\n }\n\n function __ERC20Burnable_init_unchained() internal onlyInitializing {\n }\n /**\n * @dev Destroys `amount` tokens from the caller.\n *\n * See {ERC20-_burn}.\n */\n function burn(uint256 amount) public virtual {\n _burn(_msgSender(), amount);\n }\n\n /**\n * @dev Destroys `amount` tokens from `account`, deducting from the caller's\n * allowance.\n *\n * See {ERC20-_burn} and {ERC20-allowance}.\n *\n * Requirements:\n *\n * - the caller must have allowance for ``accounts``'s tokens of at least\n * `amount`.\n */\n function burnFrom(address account, uint256 amount) public virtual {\n _spendAllowance(account, _msgSender(), amount);\n _burn(account, amount);\n }\n\n /**\n * @dev This empty reserved space is put in place to allow future versions to add new\n * variables without shifting down storage in the inheritance chain.\n * See https://docs.openzeppelin.com/contracts/4.x/upgradeable#storage_gaps\n */\n uint256[50] private __gap;\n}\n" + }, + "@openzeppelin/contracts-upgradeable/token/ERC20/extensions/IERC20MetadataUpgradeable.sol": { + "content": "// SPDX-License-Identifier: MIT\n// OpenZeppelin Contracts v4.4.1 (token/ERC20/extensions/IERC20Metadata.sol)\n\npragma solidity ^0.8.0;\n\nimport \"../IERC20Upgradeable.sol\";\n\n/**\n * @dev Interface for the optional metadata functions from the ERC20 standard.\n *\n * _Available since v4.1._\n */\ninterface IERC20MetadataUpgradeable is IERC20Upgradeable {\n /**\n * @dev Returns the name of the token.\n */\n function name() external view returns (string memory);\n\n /**\n * @dev Returns the symbol of the token.\n */\n function symbol() external view returns (string memory);\n\n /**\n * @dev Returns the decimals places of the token.\n */\n function decimals() external view returns (uint8);\n}\n" + }, + "@openzeppelin/contracts-upgradeable/token/ERC20/IERC20Upgradeable.sol": { + "content": "// SPDX-License-Identifier: MIT\n// OpenZeppelin Contracts (last updated v4.6.0) (token/ERC20/IERC20.sol)\n\npragma solidity ^0.8.0;\n\n/**\n * @dev Interface of the ERC20 standard as defined in the EIP.\n */\ninterface IERC20Upgradeable {\n /**\n * @dev Emitted when `value` tokens are moved from one account (`from`) to\n * another (`to`).\n *\n * Note that `value` may be zero.\n */\n event Transfer(address indexed from, address indexed to, uint256 value);\n\n /**\n * @dev Emitted when the allowance of a `spender` for an `owner` is set by\n * a call to {approve}. `value` is the new allowance.\n */\n event Approval(address indexed owner, address indexed spender, uint256 value);\n\n /**\n * @dev Returns the amount of tokens in existence.\n */\n function totalSupply() external view returns (uint256);\n\n /**\n * @dev Returns the amount of tokens owned by `account`.\n */\n function balanceOf(address account) external view returns (uint256);\n\n /**\n * @dev Moves `amount` tokens from the caller's account to `to`.\n *\n * Returns a boolean value indicating whether the operation succeeded.\n *\n * Emits a {Transfer} event.\n */\n function transfer(address to, uint256 amount) external returns (bool);\n\n /**\n * @dev Returns the remaining number of tokens that `spender` will be\n * allowed to spend on behalf of `owner` through {transferFrom}. This is\n * zero by default.\n *\n * This value changes when {approve} or {transferFrom} are called.\n */\n function allowance(address owner, address spender) external view returns (uint256);\n\n /**\n * @dev Sets `amount` as the allowance of `spender` over the caller's tokens.\n *\n * Returns a boolean value indicating whether the operation succeeded.\n *\n * IMPORTANT: Beware that changing an allowance with this method brings the risk\n * that someone may use both the old and the new allowance by unfortunate\n * transaction ordering. One possible solution to mitigate this race\n * condition is to first reduce the spender's allowance to 0 and set the\n * desired value afterwards:\n * https://github.com/ethereum/EIPs/issues/20#issuecomment-263524729\n *\n * Emits an {Approval} event.\n */\n function approve(address spender, uint256 amount) external returns (bool);\n\n /**\n * @dev Moves `amount` tokens from `from` to `to` using the\n * allowance mechanism. `amount` is then deducted from the caller's\n * allowance.\n *\n * Returns a boolean value indicating whether the operation succeeded.\n *\n * Emits a {Transfer} event.\n */\n function transferFrom(\n address from,\n address to,\n uint256 amount\n ) external returns (bool);\n}\n" + }, + "@openzeppelin/contracts-upgradeable/token/ERC20/utils/SafeERC20Upgradeable.sol": { + "content": "// SPDX-License-Identifier: MIT\n// OpenZeppelin Contracts (last updated v4.8.0) (token/ERC20/utils/SafeERC20.sol)\n\npragma solidity ^0.8.0;\n\nimport \"../IERC20Upgradeable.sol\";\nimport \"../extensions/draft-IERC20PermitUpgradeable.sol\";\nimport \"../../../utils/AddressUpgradeable.sol\";\n\n/**\n * @title SafeERC20\n * @dev Wrappers around ERC20 operations that throw on failure (when the token\n * contract returns false). Tokens that return no value (and instead revert or\n * throw on failure) are also supported, non-reverting calls are assumed to be\n * successful.\n * To use this library you can add a `using SafeERC20 for IERC20;` statement to your contract,\n * which allows you to call the safe operations as `token.safeTransfer(...)`, etc.\n */\nlibrary SafeERC20Upgradeable {\n using AddressUpgradeable for address;\n\n function safeTransfer(\n IERC20Upgradeable token,\n address to,\n uint256 value\n ) internal {\n _callOptionalReturn(token, abi.encodeWithSelector(token.transfer.selector, to, value));\n }\n\n function safeTransferFrom(\n IERC20Upgradeable token,\n address from,\n address to,\n uint256 value\n ) internal {\n _callOptionalReturn(token, abi.encodeWithSelector(token.transferFrom.selector, from, to, value));\n }\n\n /**\n * @dev Deprecated. This function has issues similar to the ones found in\n * {IERC20-approve}, and its usage is discouraged.\n *\n * Whenever possible, use {safeIncreaseAllowance} and\n * {safeDecreaseAllowance} instead.\n */\n function safeApprove(\n IERC20Upgradeable token,\n address spender,\n uint256 value\n ) internal {\n // safeApprove should only be called when setting an initial allowance,\n // or when resetting it to zero. To increase and decrease it, use\n // 'safeIncreaseAllowance' and 'safeDecreaseAllowance'\n require(\n (value == 0) || (token.allowance(address(this), spender) == 0),\n \"SafeERC20: approve from non-zero to non-zero allowance\"\n );\n _callOptionalReturn(token, abi.encodeWithSelector(token.approve.selector, spender, value));\n }\n\n function safeIncreaseAllowance(\n IERC20Upgradeable token,\n address spender,\n uint256 value\n ) internal {\n uint256 newAllowance = token.allowance(address(this), spender) + value;\n _callOptionalReturn(token, abi.encodeWithSelector(token.approve.selector, spender, newAllowance));\n }\n\n function safeDecreaseAllowance(\n IERC20Upgradeable token,\n address spender,\n uint256 value\n ) internal {\n unchecked {\n uint256 oldAllowance = token.allowance(address(this), spender);\n require(oldAllowance >= value, \"SafeERC20: decreased allowance below zero\");\n uint256 newAllowance = oldAllowance - value;\n _callOptionalReturn(token, abi.encodeWithSelector(token.approve.selector, spender, newAllowance));\n }\n }\n\n function safePermit(\n IERC20PermitUpgradeable token,\n address owner,\n address spender,\n uint256 value,\n uint256 deadline,\n uint8 v,\n bytes32 r,\n bytes32 s\n ) internal {\n uint256 nonceBefore = token.nonces(owner);\n token.permit(owner, spender, value, deadline, v, r, s);\n uint256 nonceAfter = token.nonces(owner);\n require(nonceAfter == nonceBefore + 1, \"SafeERC20: permit did not succeed\");\n }\n\n /**\n * @dev Imitates a Solidity high-level call (i.e. a regular function call to a contract), relaxing the requirement\n * on the return value: the return value is optional (but if data is returned, it must not be false).\n * @param token The token targeted by the call.\n * @param data The call data (encoded using abi.encode or one of its variants).\n */\n function _callOptionalReturn(IERC20Upgradeable token, bytes memory data) private {\n // We need to perform a low level call here, to bypass Solidity's return data size checking mechanism, since\n // we're implementing it ourselves. We use {Address-functionCall} to perform this call, which verifies that\n // the target address contains contract code and also asserts for success in the low-level call.\n\n bytes memory returndata = address(token).functionCall(data, \"SafeERC20: low-level call failed\");\n if (returndata.length > 0) {\n // Return data is optional\n require(abi.decode(returndata, (bool)), \"SafeERC20: ERC20 operation did not succeed\");\n }\n }\n}\n" + }, + "@openzeppelin/contracts-upgradeable/token/ERC721/IERC721Upgradeable.sol": { + "content": "// SPDX-License-Identifier: MIT\n// OpenZeppelin Contracts (last updated v4.8.0) (token/ERC721/IERC721.sol)\n\npragma solidity ^0.8.0;\n\nimport \"../../utils/introspection/IERC165Upgradeable.sol\";\n\n/**\n * @dev Required interface of an ERC721 compliant contract.\n */\ninterface IERC721Upgradeable is IERC165Upgradeable {\n /**\n * @dev Emitted when `tokenId` token is transferred from `from` to `to`.\n */\n event Transfer(address indexed from, address indexed to, uint256 indexed tokenId);\n\n /**\n * @dev Emitted when `owner` enables `approved` to manage the `tokenId` token.\n */\n event Approval(address indexed owner, address indexed approved, uint256 indexed tokenId);\n\n /**\n * @dev Emitted when `owner` enables or disables (`approved`) `operator` to manage all of its assets.\n */\n event ApprovalForAll(address indexed owner, address indexed operator, bool approved);\n\n /**\n * @dev Returns the number of tokens in ``owner``'s account.\n */\n function balanceOf(address owner) external view returns (uint256 balance);\n\n /**\n * @dev Returns the owner of the `tokenId` token.\n *\n * Requirements:\n *\n * - `tokenId` must exist.\n */\n function ownerOf(uint256 tokenId) external view returns (address owner);\n\n /**\n * @dev Safely transfers `tokenId` token from `from` to `to`.\n *\n * Requirements:\n *\n * - `from` cannot be the zero address.\n * - `to` cannot be the zero address.\n * - `tokenId` token must exist and be owned by `from`.\n * - If the caller is not `from`, it must be approved to move this token by either {approve} or {setApprovalForAll}.\n * - If `to` refers to a smart contract, it must implement {IERC721Receiver-onERC721Received}, which is called upon a safe transfer.\n *\n * Emits a {Transfer} event.\n */\n function safeTransferFrom(\n address from,\n address to,\n uint256 tokenId,\n bytes calldata data\n ) external;\n\n /**\n * @dev Safely transfers `tokenId` token from `from` to `to`, checking first that contract recipients\n * are aware of the ERC721 protocol to prevent tokens from being forever locked.\n *\n * Requirements:\n *\n * - `from` cannot be the zero address.\n * - `to` cannot be the zero address.\n * - `tokenId` token must exist and be owned by `from`.\n * - If the caller is not `from`, it must have been allowed to move this token by either {approve} or {setApprovalForAll}.\n * - If `to` refers to a smart contract, it must implement {IERC721Receiver-onERC721Received}, which is called upon a safe transfer.\n *\n * Emits a {Transfer} event.\n */\n function safeTransferFrom(\n address from,\n address to,\n uint256 tokenId\n ) external;\n\n /**\n * @dev Transfers `tokenId` token from `from` to `to`.\n *\n * WARNING: Note that the caller is responsible to confirm that the recipient is capable of receiving ERC721\n * or else they may be permanently lost. Usage of {safeTransferFrom} prevents loss, though the caller must\n * understand this adds an external call which potentially creates a reentrancy vulnerability.\n *\n * Requirements:\n *\n * - `from` cannot be the zero address.\n * - `to` cannot be the zero address.\n * - `tokenId` token must be owned by `from`.\n * - If the caller is not `from`, it must be approved to move this token by either {approve} or {setApprovalForAll}.\n *\n * Emits a {Transfer} event.\n */\n function transferFrom(\n address from,\n address to,\n uint256 tokenId\n ) external;\n\n /**\n * @dev Gives permission to `to` to transfer `tokenId` token to another account.\n * The approval is cleared when the token is transferred.\n *\n * Only a single account can be approved at a time, so approving the zero address clears previous approvals.\n *\n * Requirements:\n *\n * - The caller must own the token or be an approved operator.\n * - `tokenId` must exist.\n *\n * Emits an {Approval} event.\n */\n function approve(address to, uint256 tokenId) external;\n\n /**\n * @dev Approve or remove `operator` as an operator for the caller.\n * Operators can call {transferFrom} or {safeTransferFrom} for any token owned by the caller.\n *\n * Requirements:\n *\n * - The `operator` cannot be the caller.\n *\n * Emits an {ApprovalForAll} event.\n */\n function setApprovalForAll(address operator, bool _approved) external;\n\n /**\n * @dev Returns the account approved for `tokenId` token.\n *\n * Requirements:\n *\n * - `tokenId` must exist.\n */\n function getApproved(uint256 tokenId) external view returns (address operator);\n\n /**\n * @dev Returns if the `operator` is allowed to manage all of the assets of `owner`.\n *\n * See {setApprovalForAll}\n */\n function isApprovedForAll(address owner, address operator) external view returns (bool);\n}\n" + }, + "@openzeppelin/contracts-upgradeable/utils/AddressUpgradeable.sol": { + "content": "// SPDX-License-Identifier: MIT\n// OpenZeppelin Contracts (last updated v4.8.0) (utils/Address.sol)\n\npragma solidity ^0.8.1;\n\n/**\n * @dev Collection of functions related to the address type\n */\nlibrary AddressUpgradeable {\n /**\n * @dev Returns true if `account` is a contract.\n *\n * [IMPORTANT]\n * ====\n * It is unsafe to assume that an address for which this function returns\n * false is an externally-owned account (EOA) and not a contract.\n *\n * Among others, `isContract` will return false for the following\n * types of addresses:\n *\n * - an externally-owned account\n * - a contract in construction\n * - an address where a contract will be created\n * - an address where a contract lived, but was destroyed\n * ====\n *\n * [IMPORTANT]\n * ====\n * You shouldn't rely on `isContract` to protect against flash loan attacks!\n *\n * Preventing calls from contracts is highly discouraged. It breaks composability, breaks support for smart wallets\n * like Gnosis Safe, and does not provide security since it can be circumvented by calling from a contract\n * constructor.\n * ====\n */\n function isContract(address account) internal view returns (bool) {\n // This method relies on extcodesize/address.code.length, which returns 0\n // for contracts in construction, since the code is only stored at the end\n // of the constructor execution.\n\n return account.code.length > 0;\n }\n\n /**\n * @dev Replacement for Solidity's `transfer`: sends `amount` wei to\n * `recipient`, forwarding all available gas and reverting on errors.\n *\n * https://eips.ethereum.org/EIPS/eip-1884[EIP1884] increases the gas cost\n * of certain opcodes, possibly making contracts go over the 2300 gas limit\n * imposed by `transfer`, making them unable to receive funds via\n * `transfer`. {sendValue} removes this limitation.\n *\n * https://diligence.consensys.net/posts/2019/09/stop-using-soliditys-transfer-now/[Learn more].\n *\n * IMPORTANT: because control is transferred to `recipient`, care must be\n * taken to not create reentrancy vulnerabilities. Consider using\n * {ReentrancyGuard} or the\n * https://solidity.readthedocs.io/en/v0.5.11/security-considerations.html#use-the-checks-effects-interactions-pattern[checks-effects-interactions pattern].\n */\n function sendValue(address payable recipient, uint256 amount) internal {\n require(address(this).balance >= amount, \"Address: insufficient balance\");\n\n (bool success, ) = recipient.call{value: amount}(\"\");\n require(success, \"Address: unable to send value, recipient may have reverted\");\n }\n\n /**\n * @dev Performs a Solidity function call using a low level `call`. A\n * plain `call` is an unsafe replacement for a function call: use this\n * function instead.\n *\n * If `target` reverts with a revert reason, it is bubbled up by this\n * function (like regular Solidity function calls).\n *\n * Returns the raw returned data. To convert to the expected return value,\n * use https://solidity.readthedocs.io/en/latest/units-and-global-variables.html?highlight=abi.decode#abi-encoding-and-decoding-functions[`abi.decode`].\n *\n * Requirements:\n *\n * - `target` must be a contract.\n * - calling `target` with `data` must not revert.\n *\n * _Available since v3.1._\n */\n function functionCall(address target, bytes memory data) internal returns (bytes memory) {\n return functionCallWithValue(target, data, 0, \"Address: low-level call failed\");\n }\n\n /**\n * @dev Same as {xref-Address-functionCall-address-bytes-}[`functionCall`], but with\n * `errorMessage` as a fallback revert reason when `target` reverts.\n *\n * _Available since v3.1._\n */\n function functionCall(\n address target,\n bytes memory data,\n string memory errorMessage\n ) internal returns (bytes memory) {\n return functionCallWithValue(target, data, 0, errorMessage);\n }\n\n /**\n * @dev Same as {xref-Address-functionCall-address-bytes-}[`functionCall`],\n * but also transferring `value` wei to `target`.\n *\n * Requirements:\n *\n * - the calling contract must have an ETH balance of at least `value`.\n * - the called Solidity function must be `payable`.\n *\n * _Available since v3.1._\n */\n function functionCallWithValue(\n address target,\n bytes memory data,\n uint256 value\n ) internal returns (bytes memory) {\n return functionCallWithValue(target, data, value, \"Address: low-level call with value failed\");\n }\n\n /**\n * @dev Same as {xref-Address-functionCallWithValue-address-bytes-uint256-}[`functionCallWithValue`], but\n * with `errorMessage` as a fallback revert reason when `target` reverts.\n *\n * _Available since v3.1._\n */\n function functionCallWithValue(\n address target,\n bytes memory data,\n uint256 value,\n string memory errorMessage\n ) internal returns (bytes memory) {\n require(address(this).balance >= value, \"Address: insufficient balance for call\");\n (bool success, bytes memory returndata) = target.call{value: value}(data);\n return verifyCallResultFromTarget(target, success, returndata, errorMessage);\n }\n\n /**\n * @dev Same as {xref-Address-functionCall-address-bytes-}[`functionCall`],\n * but performing a static call.\n *\n * _Available since v3.3._\n */\n function functionStaticCall(address target, bytes memory data) internal view returns (bytes memory) {\n return functionStaticCall(target, data, \"Address: low-level static call failed\");\n }\n\n /**\n * @dev Same as {xref-Address-functionCall-address-bytes-string-}[`functionCall`],\n * but performing a static call.\n *\n * _Available since v3.3._\n */\n function functionStaticCall(\n address target,\n bytes memory data,\n string memory errorMessage\n ) internal view returns (bytes memory) {\n (bool success, bytes memory returndata) = target.staticcall(data);\n return verifyCallResultFromTarget(target, success, returndata, errorMessage);\n }\n\n /**\n * @dev Tool to verify that a low level call to smart-contract was successful, and revert (either by bubbling\n * the revert reason or using the provided one) in case of unsuccessful call or if target was not a contract.\n *\n * _Available since v4.8._\n */\n function verifyCallResultFromTarget(\n address target,\n bool success,\n bytes memory returndata,\n string memory errorMessage\n ) internal view returns (bytes memory) {\n if (success) {\n if (returndata.length == 0) {\n // only check isContract if the call was successful and the return data is empty\n // otherwise we already know that it was a contract\n require(isContract(target), \"Address: call to non-contract\");\n }\n return returndata;\n } else {\n _revert(returndata, errorMessage);\n }\n }\n\n /**\n * @dev Tool to verify that a low level call was successful, and revert if it wasn't, either by bubbling the\n * revert reason or using the provided one.\n *\n * _Available since v4.3._\n */\n function verifyCallResult(\n bool success,\n bytes memory returndata,\n string memory errorMessage\n ) internal pure returns (bytes memory) {\n if (success) {\n return returndata;\n } else {\n _revert(returndata, errorMessage);\n }\n }\n\n function _revert(bytes memory returndata, string memory errorMessage) private pure {\n // Look for revert reason and bubble it up if present\n if (returndata.length > 0) {\n // The easiest way to bubble the revert reason is using memory via assembly\n /// @solidity memory-safe-assembly\n assembly {\n let returndata_size := mload(returndata)\n revert(add(32, returndata), returndata_size)\n }\n } else {\n revert(errorMessage);\n }\n }\n}\n" + }, + "@openzeppelin/contracts-upgradeable/utils/ContextUpgradeable.sol": { + "content": "// SPDX-License-Identifier: MIT\n// OpenZeppelin Contracts v4.4.1 (utils/Context.sol)\n\npragma solidity ^0.8.0;\nimport \"../proxy/utils/Initializable.sol\";\n\n/**\n * @dev Provides information about the current execution context, including the\n * sender of the transaction and its data. While these are generally available\n * via msg.sender and msg.data, they should not be accessed in such a direct\n * manner, since when dealing with meta-transactions the account sending and\n * paying for execution may not be the actual sender (as far as an application\n * is concerned).\n *\n * This contract is only required for intermediate, library-like contracts.\n */\nabstract contract ContextUpgradeable is Initializable {\n function __Context_init() internal onlyInitializing {\n }\n\n function __Context_init_unchained() internal onlyInitializing {\n }\n function _msgSender() internal view virtual returns (address) {\n return msg.sender;\n }\n\n function _msgData() internal view virtual returns (bytes calldata) {\n return msg.data;\n }\n\n /**\n * @dev This empty reserved space is put in place to allow future versions to add new\n * variables without shifting down storage in the inheritance chain.\n * See https://docs.openzeppelin.com/contracts/4.x/upgradeable#storage_gaps\n */\n uint256[50] private __gap;\n}\n" + }, + "@openzeppelin/contracts-upgradeable/utils/CountersUpgradeable.sol": { + "content": "// SPDX-License-Identifier: MIT\n// OpenZeppelin Contracts v4.4.1 (utils/Counters.sol)\n\npragma solidity ^0.8.0;\n\n/**\n * @title Counters\n * @author Matt Condon (@shrugs)\n * @dev Provides counters that can only be incremented, decremented or reset. This can be used e.g. to track the number\n * of elements in a mapping, issuing ERC721 ids, or counting request ids.\n *\n * Include with `using Counters for Counters.Counter;`\n */\nlibrary CountersUpgradeable {\n struct Counter {\n // This variable should never be directly accessed by users of the library: interactions must be restricted to\n // the library's function. As of Solidity v0.5.2, this cannot be enforced, though there is a proposal to add\n // this feature: see https://github.com/ethereum/solidity/issues/4637\n uint256 _value; // default: 0\n }\n\n function current(Counter storage counter) internal view returns (uint256) {\n return counter._value;\n }\n\n function increment(Counter storage counter) internal {\n unchecked {\n counter._value += 1;\n }\n }\n\n function decrement(Counter storage counter) internal {\n uint256 value = counter._value;\n require(value > 0, \"Counter: decrement overflow\");\n unchecked {\n counter._value = value - 1;\n }\n }\n\n function reset(Counter storage counter) internal {\n counter._value = 0;\n }\n}\n" + }, + "@openzeppelin/contracts-upgradeable/utils/cryptography/ECDSAUpgradeable.sol": { + "content": "// SPDX-License-Identifier: MIT\n// OpenZeppelin Contracts (last updated v4.8.0) (utils/cryptography/ECDSA.sol)\n\npragma solidity ^0.8.0;\n\nimport \"../StringsUpgradeable.sol\";\n\n/**\n * @dev Elliptic Curve Digital Signature Algorithm (ECDSA) operations.\n *\n * These functions can be used to verify that a message was signed by the holder\n * of the private keys of a given address.\n */\nlibrary ECDSAUpgradeable {\n enum RecoverError {\n NoError,\n InvalidSignature,\n InvalidSignatureLength,\n InvalidSignatureS,\n InvalidSignatureV // Deprecated in v4.8\n }\n\n function _throwError(RecoverError error) private pure {\n if (error == RecoverError.NoError) {\n return; // no error: do nothing\n } else if (error == RecoverError.InvalidSignature) {\n revert(\"ECDSA: invalid signature\");\n } else if (error == RecoverError.InvalidSignatureLength) {\n revert(\"ECDSA: invalid signature length\");\n } else if (error == RecoverError.InvalidSignatureS) {\n revert(\"ECDSA: invalid signature 's' value\");\n }\n }\n\n /**\n * @dev Returns the address that signed a hashed message (`hash`) with\n * `signature` or error string. This address can then be used for verification purposes.\n *\n * The `ecrecover` EVM opcode allows for malleable (non-unique) signatures:\n * this function rejects them by requiring the `s` value to be in the lower\n * half order, and the `v` value to be either 27 or 28.\n *\n * IMPORTANT: `hash` _must_ be the result of a hash operation for the\n * verification to be secure: it is possible to craft signatures that\n * recover to arbitrary addresses for non-hashed data. A safe way to ensure\n * this is by receiving a hash of the original message (which may otherwise\n * be too long), and then calling {toEthSignedMessageHash} on it.\n *\n * Documentation for signature generation:\n * - with https://web3js.readthedocs.io/en/v1.3.4/web3-eth-accounts.html#sign[Web3.js]\n * - with https://docs.ethers.io/v5/api/signer/#Signer-signMessage[ethers]\n *\n * _Available since v4.3._\n */\n function tryRecover(bytes32 hash, bytes memory signature) internal pure returns (address, RecoverError) {\n if (signature.length == 65) {\n bytes32 r;\n bytes32 s;\n uint8 v;\n // ecrecover takes the signature parameters, and the only way to get them\n // currently is to use assembly.\n /// @solidity memory-safe-assembly\n assembly {\n r := mload(add(signature, 0x20))\n s := mload(add(signature, 0x40))\n v := byte(0, mload(add(signature, 0x60)))\n }\n return tryRecover(hash, v, r, s);\n } else {\n return (address(0), RecoverError.InvalidSignatureLength);\n }\n }\n\n /**\n * @dev Returns the address that signed a hashed message (`hash`) with\n * `signature`. This address can then be used for verification purposes.\n *\n * The `ecrecover` EVM opcode allows for malleable (non-unique) signatures:\n * this function rejects them by requiring the `s` value to be in the lower\n * half order, and the `v` value to be either 27 or 28.\n *\n * IMPORTANT: `hash` _must_ be the result of a hash operation for the\n * verification to be secure: it is possible to craft signatures that\n * recover to arbitrary addresses for non-hashed data. A safe way to ensure\n * this is by receiving a hash of the original message (which may otherwise\n * be too long), and then calling {toEthSignedMessageHash} on it.\n */\n function recover(bytes32 hash, bytes memory signature) internal pure returns (address) {\n (address recovered, RecoverError error) = tryRecover(hash, signature);\n _throwError(error);\n return recovered;\n }\n\n /**\n * @dev Overload of {ECDSA-tryRecover} that receives the `r` and `vs` short-signature fields separately.\n *\n * See https://eips.ethereum.org/EIPS/eip-2098[EIP-2098 short signatures]\n *\n * _Available since v4.3._\n */\n function tryRecover(\n bytes32 hash,\n bytes32 r,\n bytes32 vs\n ) internal pure returns (address, RecoverError) {\n bytes32 s = vs & bytes32(0x7fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff);\n uint8 v = uint8((uint256(vs) >> 255) + 27);\n return tryRecover(hash, v, r, s);\n }\n\n /**\n * @dev Overload of {ECDSA-recover} that receives the `r and `vs` short-signature fields separately.\n *\n * _Available since v4.2._\n */\n function recover(\n bytes32 hash,\n bytes32 r,\n bytes32 vs\n ) internal pure returns (address) {\n (address recovered, RecoverError error) = tryRecover(hash, r, vs);\n _throwError(error);\n return recovered;\n }\n\n /**\n * @dev Overload of {ECDSA-tryRecover} that receives the `v`,\n * `r` and `s` signature fields separately.\n *\n * _Available since v4.3._\n */\n function tryRecover(\n bytes32 hash,\n uint8 v,\n bytes32 r,\n bytes32 s\n ) internal pure returns (address, RecoverError) {\n // EIP-2 still allows signature malleability for ecrecover(). Remove this possibility and make the signature\n // unique. Appendix F in the Ethereum Yellow paper (https://ethereum.github.io/yellowpaper/paper.pdf), defines\n // the valid range for s in (301): 0 < s < secp256k1n ÷ 2 + 1, and for v in (302): v ∈ {27, 28}. Most\n // signatures from current libraries generate a unique signature with an s-value in the lower half order.\n //\n // If your library generates malleable signatures, such as s-values in the upper range, calculate a new s-value\n // with 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364141 - s1 and flip v from 27 to 28 or\n // vice versa. If your library also generates signatures with 0/1 for v instead 27/28, add 27 to v to accept\n // these malleable signatures as well.\n if (uint256(s) > 0x7FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF5D576E7357A4501DDFE92F46681B20A0) {\n return (address(0), RecoverError.InvalidSignatureS);\n }\n\n // If the signature is valid (and not malleable), return the signer address\n address signer = ecrecover(hash, v, r, s);\n if (signer == address(0)) {\n return (address(0), RecoverError.InvalidSignature);\n }\n\n return (signer, RecoverError.NoError);\n }\n\n /**\n * @dev Overload of {ECDSA-recover} that receives the `v`,\n * `r` and `s` signature fields separately.\n */\n function recover(\n bytes32 hash,\n uint8 v,\n bytes32 r,\n bytes32 s\n ) internal pure returns (address) {\n (address recovered, RecoverError error) = tryRecover(hash, v, r, s);\n _throwError(error);\n return recovered;\n }\n\n /**\n * @dev Returns an Ethereum Signed Message, created from a `hash`. This\n * produces hash corresponding to the one signed with the\n * https://eth.wiki/json-rpc/API#eth_sign[`eth_sign`]\n * JSON-RPC method as part of EIP-191.\n *\n * See {recover}.\n */\n function toEthSignedMessageHash(bytes32 hash) internal pure returns (bytes32) {\n // 32 is the length in bytes of hash,\n // enforced by the type signature above\n return keccak256(abi.encodePacked(\"\\x19Ethereum Signed Message:\\n32\", hash));\n }\n\n /**\n * @dev Returns an Ethereum Signed Message, created from `s`. This\n * produces hash corresponding to the one signed with the\n * https://eth.wiki/json-rpc/API#eth_sign[`eth_sign`]\n * JSON-RPC method as part of EIP-191.\n *\n * See {recover}.\n */\n function toEthSignedMessageHash(bytes memory s) internal pure returns (bytes32) {\n return keccak256(abi.encodePacked(\"\\x19Ethereum Signed Message:\\n\", StringsUpgradeable.toString(s.length), s));\n }\n\n /**\n * @dev Returns an Ethereum Signed Typed Data, created from a\n * `domainSeparator` and a `structHash`. This produces hash corresponding\n * to the one signed with the\n * https://eips.ethereum.org/EIPS/eip-712[`eth_signTypedData`]\n * JSON-RPC method as part of EIP-712.\n *\n * See {recover}.\n */\n function toTypedDataHash(bytes32 domainSeparator, bytes32 structHash) internal pure returns (bytes32) {\n return keccak256(abi.encodePacked(\"\\x19\\x01\", domainSeparator, structHash));\n }\n}\n" + }, + "@openzeppelin/contracts-upgradeable/utils/cryptography/EIP712Upgradeable.sol": { + "content": "// SPDX-License-Identifier: MIT\n// OpenZeppelin Contracts (last updated v4.8.0) (utils/cryptography/EIP712.sol)\n\npragma solidity ^0.8.0;\n\nimport \"./ECDSAUpgradeable.sol\";\nimport \"../../proxy/utils/Initializable.sol\";\n\n/**\n * @dev https://eips.ethereum.org/EIPS/eip-712[EIP 712] is a standard for hashing and signing of typed structured data.\n *\n * The encoding specified in the EIP is very generic, and such a generic implementation in Solidity is not feasible,\n * thus this contract does not implement the encoding itself. Protocols need to implement the type-specific encoding\n * they need in their contracts using a combination of `abi.encode` and `keccak256`.\n *\n * This contract implements the EIP 712 domain separator ({_domainSeparatorV4}) that is used as part of the encoding\n * scheme, and the final step of the encoding to obtain the message digest that is then signed via ECDSA\n * ({_hashTypedDataV4}).\n *\n * The implementation of the domain separator was designed to be as efficient as possible while still properly updating\n * the chain id to protect against replay attacks on an eventual fork of the chain.\n *\n * NOTE: This contract implements the version of the encoding known as \"v4\", as implemented by the JSON RPC method\n * https://docs.metamask.io/guide/signing-data.html[`eth_signTypedDataV4` in MetaMask].\n *\n * _Available since v3.4._\n *\n * @custom:storage-size 52\n */\nabstract contract EIP712Upgradeable is Initializable {\n /* solhint-disable var-name-mixedcase */\n bytes32 private _HASHED_NAME;\n bytes32 private _HASHED_VERSION;\n bytes32 private constant _TYPE_HASH = keccak256(\"EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)\");\n\n /* solhint-enable var-name-mixedcase */\n\n /**\n * @dev Initializes the domain separator and parameter caches.\n *\n * The meaning of `name` and `version` is specified in\n * https://eips.ethereum.org/EIPS/eip-712#definition-of-domainseparator[EIP 712]:\n *\n * - `name`: the user readable name of the signing domain, i.e. the name of the DApp or the protocol.\n * - `version`: the current major version of the signing domain.\n *\n * NOTE: These parameters cannot be changed except through a xref:learn::upgrading-smart-contracts.adoc[smart\n * contract upgrade].\n */\n function __EIP712_init(string memory name, string memory version) internal onlyInitializing {\n __EIP712_init_unchained(name, version);\n }\n\n function __EIP712_init_unchained(string memory name, string memory version) internal onlyInitializing {\n bytes32 hashedName = keccak256(bytes(name));\n bytes32 hashedVersion = keccak256(bytes(version));\n _HASHED_NAME = hashedName;\n _HASHED_VERSION = hashedVersion;\n }\n\n /**\n * @dev Returns the domain separator for the current chain.\n */\n function _domainSeparatorV4() internal view returns (bytes32) {\n return _buildDomainSeparator(_TYPE_HASH, _EIP712NameHash(), _EIP712VersionHash());\n }\n\n function _buildDomainSeparator(\n bytes32 typeHash,\n bytes32 nameHash,\n bytes32 versionHash\n ) private view returns (bytes32) {\n return keccak256(abi.encode(typeHash, nameHash, versionHash, block.chainid, address(this)));\n }\n\n /**\n * @dev Given an already https://eips.ethereum.org/EIPS/eip-712#definition-of-hashstruct[hashed struct], this\n * function returns the hash of the fully encoded EIP712 message for this domain.\n *\n * This hash can be used together with {ECDSA-recover} to obtain the signer of a message. For example:\n *\n * ```solidity\n * bytes32 digest = _hashTypedDataV4(keccak256(abi.encode(\n * keccak256(\"Mail(address to,string contents)\"),\n * mailTo,\n * keccak256(bytes(mailContents))\n * )));\n * address signer = ECDSA.recover(digest, signature);\n * ```\n */\n function _hashTypedDataV4(bytes32 structHash) internal view virtual returns (bytes32) {\n return ECDSAUpgradeable.toTypedDataHash(_domainSeparatorV4(), structHash);\n }\n\n /**\n * @dev The hash of the name parameter for the EIP712 domain.\n *\n * NOTE: This function reads from storage by default, but can be redefined to return a constant value if gas costs\n * are a concern.\n */\n function _EIP712NameHash() internal virtual view returns (bytes32) {\n return _HASHED_NAME;\n }\n\n /**\n * @dev The hash of the version parameter for the EIP712 domain.\n *\n * NOTE: This function reads from storage by default, but can be redefined to return a constant value if gas costs\n * are a concern.\n */\n function _EIP712VersionHash() internal virtual view returns (bytes32) {\n return _HASHED_VERSION;\n }\n\n /**\n * @dev This empty reserved space is put in place to allow future versions to add new\n * variables without shifting down storage in the inheritance chain.\n * See https://docs.openzeppelin.com/contracts/4.x/upgradeable#storage_gaps\n */\n uint256[50] private __gap;\n}\n" + }, + "@openzeppelin/contracts-upgradeable/utils/introspection/IERC165Upgradeable.sol": { + "content": "// SPDX-License-Identifier: MIT\n// OpenZeppelin Contracts v4.4.1 (utils/introspection/IERC165.sol)\n\npragma solidity ^0.8.0;\n\n/**\n * @dev Interface of the ERC165 standard, as defined in the\n * https://eips.ethereum.org/EIPS/eip-165[EIP].\n *\n * Implementers can declare support of contract interfaces, which can then be\n * queried by others ({ERC165Checker}).\n *\n * For an implementation, see {ERC165}.\n */\ninterface IERC165Upgradeable {\n /**\n * @dev Returns true if this contract implements the interface defined by\n * `interfaceId`. See the corresponding\n * https://eips.ethereum.org/EIPS/eip-165#how-interfaces-are-identified[EIP section]\n * to learn more about how these ids are created.\n *\n * This function call must use less than 30 000 gas.\n */\n function supportsInterface(bytes4 interfaceId) external view returns (bool);\n}\n" + }, + "@openzeppelin/contracts-upgradeable/utils/math/MathUpgradeable.sol": { + "content": "// SPDX-License-Identifier: MIT\n// OpenZeppelin Contracts (last updated v4.8.0) (utils/math/Math.sol)\n\npragma solidity ^0.8.0;\n\n/**\n * @dev Standard math utilities missing in the Solidity language.\n */\nlibrary MathUpgradeable {\n enum Rounding {\n Down, // Toward negative infinity\n Up, // Toward infinity\n Zero // Toward zero\n }\n\n /**\n * @dev Returns the largest of two numbers.\n */\n function max(uint256 a, uint256 b) internal pure returns (uint256) {\n return a > b ? a : b;\n }\n\n /**\n * @dev Returns the smallest of two numbers.\n */\n function min(uint256 a, uint256 b) internal pure returns (uint256) {\n return a < b ? a : b;\n }\n\n /**\n * @dev Returns the average of two numbers. The result is rounded towards\n * zero.\n */\n function average(uint256 a, uint256 b) internal pure returns (uint256) {\n // (a + b) / 2 can overflow.\n return (a & b) + (a ^ b) / 2;\n }\n\n /**\n * @dev Returns the ceiling of the division of two numbers.\n *\n * This differs from standard division with `/` in that it rounds up instead\n * of rounding down.\n */\n function ceilDiv(uint256 a, uint256 b) internal pure returns (uint256) {\n // (a + b - 1) / b can overflow on addition, so we distribute.\n return a == 0 ? 0 : (a - 1) / b + 1;\n }\n\n /**\n * @notice Calculates floor(x * y / denominator) with full precision. Throws if result overflows a uint256 or denominator == 0\n * @dev Original credit to Remco Bloemen under MIT license (https://xn--2-umb.com/21/muldiv)\n * with further edits by Uniswap Labs also under MIT license.\n */\n function mulDiv(\n uint256 x,\n uint256 y,\n uint256 denominator\n ) internal pure returns (uint256 result) {\n unchecked {\n // 512-bit multiply [prod1 prod0] = x * y. Compute the product mod 2^256 and mod 2^256 - 1, then use\n // use the Chinese Remainder Theorem to reconstruct the 512 bit result. The result is stored in two 256\n // variables such that product = prod1 * 2^256 + prod0.\n uint256 prod0; // Least significant 256 bits of the product\n uint256 prod1; // Most significant 256 bits of the product\n assembly {\n let mm := mulmod(x, y, not(0))\n prod0 := mul(x, y)\n prod1 := sub(sub(mm, prod0), lt(mm, prod0))\n }\n\n // Handle non-overflow cases, 256 by 256 division.\n if (prod1 == 0) {\n return prod0 / denominator;\n }\n\n // Make sure the result is less than 2^256. Also prevents denominator == 0.\n require(denominator > prod1);\n\n ///////////////////////////////////////////////\n // 512 by 256 division.\n ///////////////////////////////////////////////\n\n // Make division exact by subtracting the remainder from [prod1 prod0].\n uint256 remainder;\n assembly {\n // Compute remainder using mulmod.\n remainder := mulmod(x, y, denominator)\n\n // Subtract 256 bit number from 512 bit number.\n prod1 := sub(prod1, gt(remainder, prod0))\n prod0 := sub(prod0, remainder)\n }\n\n // Factor powers of two out of denominator and compute largest power of two divisor of denominator. Always >= 1.\n // See https://cs.stackexchange.com/q/138556/92363.\n\n // Does not overflow because the denominator cannot be zero at this stage in the function.\n uint256 twos = denominator & (~denominator + 1);\n assembly {\n // Divide denominator by twos.\n denominator := div(denominator, twos)\n\n // Divide [prod1 prod0] by twos.\n prod0 := div(prod0, twos)\n\n // Flip twos such that it is 2^256 / twos. If twos is zero, then it becomes one.\n twos := add(div(sub(0, twos), twos), 1)\n }\n\n // Shift in bits from prod1 into prod0.\n prod0 |= prod1 * twos;\n\n // Invert denominator mod 2^256. Now that denominator is an odd number, it has an inverse modulo 2^256 such\n // that denominator * inv = 1 mod 2^256. Compute the inverse by starting with a seed that is correct for\n // four bits. That is, denominator * inv = 1 mod 2^4.\n uint256 inverse = (3 * denominator) ^ 2;\n\n // Use the Newton-Raphson iteration to improve the precision. Thanks to Hensel's lifting lemma, this also works\n // in modular arithmetic, doubling the correct bits in each step.\n inverse *= 2 - denominator * inverse; // inverse mod 2^8\n inverse *= 2 - denominator * inverse; // inverse mod 2^16\n inverse *= 2 - denominator * inverse; // inverse mod 2^32\n inverse *= 2 - denominator * inverse; // inverse mod 2^64\n inverse *= 2 - denominator * inverse; // inverse mod 2^128\n inverse *= 2 - denominator * inverse; // inverse mod 2^256\n\n // Because the division is now exact we can divide by multiplying with the modular inverse of denominator.\n // This will give us the correct result modulo 2^256. Since the preconditions guarantee that the outcome is\n // less than 2^256, this is the final result. We don't need to compute the high bits of the result and prod1\n // is no longer required.\n result = prod0 * inverse;\n return result;\n }\n }\n\n /**\n * @notice Calculates x * y / denominator with full precision, following the selected rounding direction.\n */\n function mulDiv(\n uint256 x,\n uint256 y,\n uint256 denominator,\n Rounding rounding\n ) internal pure returns (uint256) {\n uint256 result = mulDiv(x, y, denominator);\n if (rounding == Rounding.Up && mulmod(x, y, denominator) > 0) {\n result += 1;\n }\n return result;\n }\n\n /**\n * @dev Returns the square root of a number. If the number is not a perfect square, the value is rounded down.\n *\n * Inspired by Henry S. Warren, Jr.'s \"Hacker's Delight\" (Chapter 11).\n */\n function sqrt(uint256 a) internal pure returns (uint256) {\n if (a == 0) {\n return 0;\n }\n\n // For our first guess, we get the biggest power of 2 which is smaller than the square root of the target.\n //\n // We know that the \"msb\" (most significant bit) of our target number `a` is a power of 2 such that we have\n // `msb(a) <= a < 2*msb(a)`. This value can be written `msb(a)=2**k` with `k=log2(a)`.\n //\n // This can be rewritten `2**log2(a) <= a < 2**(log2(a) + 1)`\n // → `sqrt(2**k) <= sqrt(a) < sqrt(2**(k+1))`\n // → `2**(k/2) <= sqrt(a) < 2**((k+1)/2) <= 2**(k/2 + 1)`\n //\n // Consequently, `2**(log2(a) / 2)` is a good first approximation of `sqrt(a)` with at least 1 correct bit.\n uint256 result = 1 << (log2(a) >> 1);\n\n // At this point `result` is an estimation with one bit of precision. We know the true value is a uint128,\n // since it is the square root of a uint256. Newton's method converges quadratically (precision doubles at\n // every iteration). We thus need at most 7 iteration to turn our partial result with one bit of precision\n // into the expected uint128 result.\n unchecked {\n result = (result + a / result) >> 1;\n result = (result + a / result) >> 1;\n result = (result + a / result) >> 1;\n result = (result + a / result) >> 1;\n result = (result + a / result) >> 1;\n result = (result + a / result) >> 1;\n result = (result + a / result) >> 1;\n return min(result, a / result);\n }\n }\n\n /**\n * @notice Calculates sqrt(a), following the selected rounding direction.\n */\n function sqrt(uint256 a, Rounding rounding) internal pure returns (uint256) {\n unchecked {\n uint256 result = sqrt(a);\n return result + (rounding == Rounding.Up && result * result < a ? 1 : 0);\n }\n }\n\n /**\n * @dev Return the log in base 2, rounded down, of a positive value.\n * Returns 0 if given 0.\n */\n function log2(uint256 value) internal pure returns (uint256) {\n uint256 result = 0;\n unchecked {\n if (value >> 128 > 0) {\n value >>= 128;\n result += 128;\n }\n if (value >> 64 > 0) {\n value >>= 64;\n result += 64;\n }\n if (value >> 32 > 0) {\n value >>= 32;\n result += 32;\n }\n if (value >> 16 > 0) {\n value >>= 16;\n result += 16;\n }\n if (value >> 8 > 0) {\n value >>= 8;\n result += 8;\n }\n if (value >> 4 > 0) {\n value >>= 4;\n result += 4;\n }\n if (value >> 2 > 0) {\n value >>= 2;\n result += 2;\n }\n if (value >> 1 > 0) {\n result += 1;\n }\n }\n return result;\n }\n\n /**\n * @dev Return the log in base 2, following the selected rounding direction, of a positive value.\n * Returns 0 if given 0.\n */\n function log2(uint256 value, Rounding rounding) internal pure returns (uint256) {\n unchecked {\n uint256 result = log2(value);\n return result + (rounding == Rounding.Up && 1 << result < value ? 1 : 0);\n }\n }\n\n /**\n * @dev Return the log in base 10, rounded down, of a positive value.\n * Returns 0 if given 0.\n */\n function log10(uint256 value) internal pure returns (uint256) {\n uint256 result = 0;\n unchecked {\n if (value >= 10**64) {\n value /= 10**64;\n result += 64;\n }\n if (value >= 10**32) {\n value /= 10**32;\n result += 32;\n }\n if (value >= 10**16) {\n value /= 10**16;\n result += 16;\n }\n if (value >= 10**8) {\n value /= 10**8;\n result += 8;\n }\n if (value >= 10**4) {\n value /= 10**4;\n result += 4;\n }\n if (value >= 10**2) {\n value /= 10**2;\n result += 2;\n }\n if (value >= 10**1) {\n result += 1;\n }\n }\n return result;\n }\n\n /**\n * @dev Return the log in base 10, following the selected rounding direction, of a positive value.\n * Returns 0 if given 0.\n */\n function log10(uint256 value, Rounding rounding) internal pure returns (uint256) {\n unchecked {\n uint256 result = log10(value);\n return result + (rounding == Rounding.Up && 10**result < value ? 1 : 0);\n }\n }\n\n /**\n * @dev Return the log in base 256, rounded down, of a positive value.\n * Returns 0 if given 0.\n *\n * Adding one to the result gives the number of pairs of hex symbols needed to represent `value` as a hex string.\n */\n function log256(uint256 value) internal pure returns (uint256) {\n uint256 result = 0;\n unchecked {\n if (value >> 128 > 0) {\n value >>= 128;\n result += 16;\n }\n if (value >> 64 > 0) {\n value >>= 64;\n result += 8;\n }\n if (value >> 32 > 0) {\n value >>= 32;\n result += 4;\n }\n if (value >> 16 > 0) {\n value >>= 16;\n result += 2;\n }\n if (value >> 8 > 0) {\n result += 1;\n }\n }\n return result;\n }\n\n /**\n * @dev Return the log in base 10, following the selected rounding direction, of a positive value.\n * Returns 0 if given 0.\n */\n function log256(uint256 value, Rounding rounding) internal pure returns (uint256) {\n unchecked {\n uint256 result = log256(value);\n return result + (rounding == Rounding.Up && 1 << (result * 8) < value ? 1 : 0);\n }\n }\n}\n" + }, + "@openzeppelin/contracts-upgradeable/utils/math/SafeCastUpgradeable.sol": { + "content": "// SPDX-License-Identifier: MIT\n// OpenZeppelin Contracts (last updated v4.8.0) (utils/math/SafeCast.sol)\n// This file was procedurally generated from scripts/generate/templates/SafeCast.js.\n\npragma solidity ^0.8.0;\n\n/**\n * @dev Wrappers over Solidity's uintXX/intXX casting operators with added overflow\n * checks.\n *\n * Downcasting from uint256/int256 in Solidity does not revert on overflow. This can\n * easily result in undesired exploitation or bugs, since developers usually\n * assume that overflows raise errors. `SafeCast` restores this intuition by\n * reverting the transaction when such an operation overflows.\n *\n * Using this library instead of the unchecked operations eliminates an entire\n * class of bugs, so it's recommended to use it always.\n *\n * Can be combined with {SafeMath} and {SignedSafeMath} to extend it to smaller types, by performing\n * all math on `uint256` and `int256` and then downcasting.\n */\nlibrary SafeCastUpgradeable {\n /**\n * @dev Returns the downcasted uint248 from uint256, reverting on\n * overflow (when the input is greater than largest uint248).\n *\n * Counterpart to Solidity's `uint248` operator.\n *\n * Requirements:\n *\n * - input must fit into 248 bits\n *\n * _Available since v4.7._\n */\n function toUint248(uint256 value) internal pure returns (uint248) {\n require(value <= type(uint248).max, \"SafeCast: value doesn't fit in 248 bits\");\n return uint248(value);\n }\n\n /**\n * @dev Returns the downcasted uint240 from uint256, reverting on\n * overflow (when the input is greater than largest uint240).\n *\n * Counterpart to Solidity's `uint240` operator.\n *\n * Requirements:\n *\n * - input must fit into 240 bits\n *\n * _Available since v4.7._\n */\n function toUint240(uint256 value) internal pure returns (uint240) {\n require(value <= type(uint240).max, \"SafeCast: value doesn't fit in 240 bits\");\n return uint240(value);\n }\n\n /**\n * @dev Returns the downcasted uint232 from uint256, reverting on\n * overflow (when the input is greater than largest uint232).\n *\n * Counterpart to Solidity's `uint232` operator.\n *\n * Requirements:\n *\n * - input must fit into 232 bits\n *\n * _Available since v4.7._\n */\n function toUint232(uint256 value) internal pure returns (uint232) {\n require(value <= type(uint232).max, \"SafeCast: value doesn't fit in 232 bits\");\n return uint232(value);\n }\n\n /**\n * @dev Returns the downcasted uint224 from uint256, reverting on\n * overflow (when the input is greater than largest uint224).\n *\n * Counterpart to Solidity's `uint224` operator.\n *\n * Requirements:\n *\n * - input must fit into 224 bits\n *\n * _Available since v4.2._\n */\n function toUint224(uint256 value) internal pure returns (uint224) {\n require(value <= type(uint224).max, \"SafeCast: value doesn't fit in 224 bits\");\n return uint224(value);\n }\n\n /**\n * @dev Returns the downcasted uint216 from uint256, reverting on\n * overflow (when the input is greater than largest uint216).\n *\n * Counterpart to Solidity's `uint216` operator.\n *\n * Requirements:\n *\n * - input must fit into 216 bits\n *\n * _Available since v4.7._\n */\n function toUint216(uint256 value) internal pure returns (uint216) {\n require(value <= type(uint216).max, \"SafeCast: value doesn't fit in 216 bits\");\n return uint216(value);\n }\n\n /**\n * @dev Returns the downcasted uint208 from uint256, reverting on\n * overflow (when the input is greater than largest uint208).\n *\n * Counterpart to Solidity's `uint208` operator.\n *\n * Requirements:\n *\n * - input must fit into 208 bits\n *\n * _Available since v4.7._\n */\n function toUint208(uint256 value) internal pure returns (uint208) {\n require(value <= type(uint208).max, \"SafeCast: value doesn't fit in 208 bits\");\n return uint208(value);\n }\n\n /**\n * @dev Returns the downcasted uint200 from uint256, reverting on\n * overflow (when the input is greater than largest uint200).\n *\n * Counterpart to Solidity's `uint200` operator.\n *\n * Requirements:\n *\n * - input must fit into 200 bits\n *\n * _Available since v4.7._\n */\n function toUint200(uint256 value) internal pure returns (uint200) {\n require(value <= type(uint200).max, \"SafeCast: value doesn't fit in 200 bits\");\n return uint200(value);\n }\n\n /**\n * @dev Returns the downcasted uint192 from uint256, reverting on\n * overflow (when the input is greater than largest uint192).\n *\n * Counterpart to Solidity's `uint192` operator.\n *\n * Requirements:\n *\n * - input must fit into 192 bits\n *\n * _Available since v4.7._\n */\n function toUint192(uint256 value) internal pure returns (uint192) {\n require(value <= type(uint192).max, \"SafeCast: value doesn't fit in 192 bits\");\n return uint192(value);\n }\n\n /**\n * @dev Returns the downcasted uint184 from uint256, reverting on\n * overflow (when the input is greater than largest uint184).\n *\n * Counterpart to Solidity's `uint184` operator.\n *\n * Requirements:\n *\n * - input must fit into 184 bits\n *\n * _Available since v4.7._\n */\n function toUint184(uint256 value) internal pure returns (uint184) {\n require(value <= type(uint184).max, \"SafeCast: value doesn't fit in 184 bits\");\n return uint184(value);\n }\n\n /**\n * @dev Returns the downcasted uint176 from uint256, reverting on\n * overflow (when the input is greater than largest uint176).\n *\n * Counterpart to Solidity's `uint176` operator.\n *\n * Requirements:\n *\n * - input must fit into 176 bits\n *\n * _Available since v4.7._\n */\n function toUint176(uint256 value) internal pure returns (uint176) {\n require(value <= type(uint176).max, \"SafeCast: value doesn't fit in 176 bits\");\n return uint176(value);\n }\n\n /**\n * @dev Returns the downcasted uint168 from uint256, reverting on\n * overflow (when the input is greater than largest uint168).\n *\n * Counterpart to Solidity's `uint168` operator.\n *\n * Requirements:\n *\n * - input must fit into 168 bits\n *\n * _Available since v4.7._\n */\n function toUint168(uint256 value) internal pure returns (uint168) {\n require(value <= type(uint168).max, \"SafeCast: value doesn't fit in 168 bits\");\n return uint168(value);\n }\n\n /**\n * @dev Returns the downcasted uint160 from uint256, reverting on\n * overflow (when the input is greater than largest uint160).\n *\n * Counterpart to Solidity's `uint160` operator.\n *\n * Requirements:\n *\n * - input must fit into 160 bits\n *\n * _Available since v4.7._\n */\n function toUint160(uint256 value) internal pure returns (uint160) {\n require(value <= type(uint160).max, \"SafeCast: value doesn't fit in 160 bits\");\n return uint160(value);\n }\n\n /**\n * @dev Returns the downcasted uint152 from uint256, reverting on\n * overflow (when the input is greater than largest uint152).\n *\n * Counterpart to Solidity's `uint152` operator.\n *\n * Requirements:\n *\n * - input must fit into 152 bits\n *\n * _Available since v4.7._\n */\n function toUint152(uint256 value) internal pure returns (uint152) {\n require(value <= type(uint152).max, \"SafeCast: value doesn't fit in 152 bits\");\n return uint152(value);\n }\n\n /**\n * @dev Returns the downcasted uint144 from uint256, reverting on\n * overflow (when the input is greater than largest uint144).\n *\n * Counterpart to Solidity's `uint144` operator.\n *\n * Requirements:\n *\n * - input must fit into 144 bits\n *\n * _Available since v4.7._\n */\n function toUint144(uint256 value) internal pure returns (uint144) {\n require(value <= type(uint144).max, \"SafeCast: value doesn't fit in 144 bits\");\n return uint144(value);\n }\n\n /**\n * @dev Returns the downcasted uint136 from uint256, reverting on\n * overflow (when the input is greater than largest uint136).\n *\n * Counterpart to Solidity's `uint136` operator.\n *\n * Requirements:\n *\n * - input must fit into 136 bits\n *\n * _Available since v4.7._\n */\n function toUint136(uint256 value) internal pure returns (uint136) {\n require(value <= type(uint136).max, \"SafeCast: value doesn't fit in 136 bits\");\n return uint136(value);\n }\n\n /**\n * @dev Returns the downcasted uint128 from uint256, reverting on\n * overflow (when the input is greater than largest uint128).\n *\n * Counterpart to Solidity's `uint128` operator.\n *\n * Requirements:\n *\n * - input must fit into 128 bits\n *\n * _Available since v2.5._\n */\n function toUint128(uint256 value) internal pure returns (uint128) {\n require(value <= type(uint128).max, \"SafeCast: value doesn't fit in 128 bits\");\n return uint128(value);\n }\n\n /**\n * @dev Returns the downcasted uint120 from uint256, reverting on\n * overflow (when the input is greater than largest uint120).\n *\n * Counterpart to Solidity's `uint120` operator.\n *\n * Requirements:\n *\n * - input must fit into 120 bits\n *\n * _Available since v4.7._\n */\n function toUint120(uint256 value) internal pure returns (uint120) {\n require(value <= type(uint120).max, \"SafeCast: value doesn't fit in 120 bits\");\n return uint120(value);\n }\n\n /**\n * @dev Returns the downcasted uint112 from uint256, reverting on\n * overflow (when the input is greater than largest uint112).\n *\n * Counterpart to Solidity's `uint112` operator.\n *\n * Requirements:\n *\n * - input must fit into 112 bits\n *\n * _Available since v4.7._\n */\n function toUint112(uint256 value) internal pure returns (uint112) {\n require(value <= type(uint112).max, \"SafeCast: value doesn't fit in 112 bits\");\n return uint112(value);\n }\n\n /**\n * @dev Returns the downcasted uint104 from uint256, reverting on\n * overflow (when the input is greater than largest uint104).\n *\n * Counterpart to Solidity's `uint104` operator.\n *\n * Requirements:\n *\n * - input must fit into 104 bits\n *\n * _Available since v4.7._\n */\n function toUint104(uint256 value) internal pure returns (uint104) {\n require(value <= type(uint104).max, \"SafeCast: value doesn't fit in 104 bits\");\n return uint104(value);\n }\n\n /**\n * @dev Returns the downcasted uint96 from uint256, reverting on\n * overflow (when the input is greater than largest uint96).\n *\n * Counterpart to Solidity's `uint96` operator.\n *\n * Requirements:\n *\n * - input must fit into 96 bits\n *\n * _Available since v4.2._\n */\n function toUint96(uint256 value) internal pure returns (uint96) {\n require(value <= type(uint96).max, \"SafeCast: value doesn't fit in 96 bits\");\n return uint96(value);\n }\n\n /**\n * @dev Returns the downcasted uint88 from uint256, reverting on\n * overflow (when the input is greater than largest uint88).\n *\n * Counterpart to Solidity's `uint88` operator.\n *\n * Requirements:\n *\n * - input must fit into 88 bits\n *\n * _Available since v4.7._\n */\n function toUint88(uint256 value) internal pure returns (uint88) {\n require(value <= type(uint88).max, \"SafeCast: value doesn't fit in 88 bits\");\n return uint88(value);\n }\n\n /**\n * @dev Returns the downcasted uint80 from uint256, reverting on\n * overflow (when the input is greater than largest uint80).\n *\n * Counterpart to Solidity's `uint80` operator.\n *\n * Requirements:\n *\n * - input must fit into 80 bits\n *\n * _Available since v4.7._\n */\n function toUint80(uint256 value) internal pure returns (uint80) {\n require(value <= type(uint80).max, \"SafeCast: value doesn't fit in 80 bits\");\n return uint80(value);\n }\n\n /**\n * @dev Returns the downcasted uint72 from uint256, reverting on\n * overflow (when the input is greater than largest uint72).\n *\n * Counterpart to Solidity's `uint72` operator.\n *\n * Requirements:\n *\n * - input must fit into 72 bits\n *\n * _Available since v4.7._\n */\n function toUint72(uint256 value) internal pure returns (uint72) {\n require(value <= type(uint72).max, \"SafeCast: value doesn't fit in 72 bits\");\n return uint72(value);\n }\n\n /**\n * @dev Returns the downcasted uint64 from uint256, reverting on\n * overflow (when the input is greater than largest uint64).\n *\n * Counterpart to Solidity's `uint64` operator.\n *\n * Requirements:\n *\n * - input must fit into 64 bits\n *\n * _Available since v2.5._\n */\n function toUint64(uint256 value) internal pure returns (uint64) {\n require(value <= type(uint64).max, \"SafeCast: value doesn't fit in 64 bits\");\n return uint64(value);\n }\n\n /**\n * @dev Returns the downcasted uint56 from uint256, reverting on\n * overflow (when the input is greater than largest uint56).\n *\n * Counterpart to Solidity's `uint56` operator.\n *\n * Requirements:\n *\n * - input must fit into 56 bits\n *\n * _Available since v4.7._\n */\n function toUint56(uint256 value) internal pure returns (uint56) {\n require(value <= type(uint56).max, \"SafeCast: value doesn't fit in 56 bits\");\n return uint56(value);\n }\n\n /**\n * @dev Returns the downcasted uint48 from uint256, reverting on\n * overflow (when the input is greater than largest uint48).\n *\n * Counterpart to Solidity's `uint48` operator.\n *\n * Requirements:\n *\n * - input must fit into 48 bits\n *\n * _Available since v4.7._\n */\n function toUint48(uint256 value) internal pure returns (uint48) {\n require(value <= type(uint48).max, \"SafeCast: value doesn't fit in 48 bits\");\n return uint48(value);\n }\n\n /**\n * @dev Returns the downcasted uint40 from uint256, reverting on\n * overflow (when the input is greater than largest uint40).\n *\n * Counterpart to Solidity's `uint40` operator.\n *\n * Requirements:\n *\n * - input must fit into 40 bits\n *\n * _Available since v4.7._\n */\n function toUint40(uint256 value) internal pure returns (uint40) {\n require(value <= type(uint40).max, \"SafeCast: value doesn't fit in 40 bits\");\n return uint40(value);\n }\n\n /**\n * @dev Returns the downcasted uint32 from uint256, reverting on\n * overflow (when the input is greater than largest uint32).\n *\n * Counterpart to Solidity's `uint32` operator.\n *\n * Requirements:\n *\n * - input must fit into 32 bits\n *\n * _Available since v2.5._\n */\n function toUint32(uint256 value) internal pure returns (uint32) {\n require(value <= type(uint32).max, \"SafeCast: value doesn't fit in 32 bits\");\n return uint32(value);\n }\n\n /**\n * @dev Returns the downcasted uint24 from uint256, reverting on\n * overflow (when the input is greater than largest uint24).\n *\n * Counterpart to Solidity's `uint24` operator.\n *\n * Requirements:\n *\n * - input must fit into 24 bits\n *\n * _Available since v4.7._\n */\n function toUint24(uint256 value) internal pure returns (uint24) {\n require(value <= type(uint24).max, \"SafeCast: value doesn't fit in 24 bits\");\n return uint24(value);\n }\n\n /**\n * @dev Returns the downcasted uint16 from uint256, reverting on\n * overflow (when the input is greater than largest uint16).\n *\n * Counterpart to Solidity's `uint16` operator.\n *\n * Requirements:\n *\n * - input must fit into 16 bits\n *\n * _Available since v2.5._\n */\n function toUint16(uint256 value) internal pure returns (uint16) {\n require(value <= type(uint16).max, \"SafeCast: value doesn't fit in 16 bits\");\n return uint16(value);\n }\n\n /**\n * @dev Returns the downcasted uint8 from uint256, reverting on\n * overflow (when the input is greater than largest uint8).\n *\n * Counterpart to Solidity's `uint8` operator.\n *\n * Requirements:\n *\n * - input must fit into 8 bits\n *\n * _Available since v2.5._\n */\n function toUint8(uint256 value) internal pure returns (uint8) {\n require(value <= type(uint8).max, \"SafeCast: value doesn't fit in 8 bits\");\n return uint8(value);\n }\n\n /**\n * @dev Converts a signed int256 into an unsigned uint256.\n *\n * Requirements:\n *\n * - input must be greater than or equal to 0.\n *\n * _Available since v3.0._\n */\n function toUint256(int256 value) internal pure returns (uint256) {\n require(value >= 0, \"SafeCast: value must be positive\");\n return uint256(value);\n }\n\n /**\n * @dev Returns the downcasted int248 from int256, reverting on\n * overflow (when the input is less than smallest int248 or\n * greater than largest int248).\n *\n * Counterpart to Solidity's `int248` operator.\n *\n * Requirements:\n *\n * - input must fit into 248 bits\n *\n * _Available since v4.7._\n */\n function toInt248(int256 value) internal pure returns (int248 downcasted) {\n downcasted = int248(value);\n require(downcasted == value, \"SafeCast: value doesn't fit in 248 bits\");\n }\n\n /**\n * @dev Returns the downcasted int240 from int256, reverting on\n * overflow (when the input is less than smallest int240 or\n * greater than largest int240).\n *\n * Counterpart to Solidity's `int240` operator.\n *\n * Requirements:\n *\n * - input must fit into 240 bits\n *\n * _Available since v4.7._\n */\n function toInt240(int256 value) internal pure returns (int240 downcasted) {\n downcasted = int240(value);\n require(downcasted == value, \"SafeCast: value doesn't fit in 240 bits\");\n }\n\n /**\n * @dev Returns the downcasted int232 from int256, reverting on\n * overflow (when the input is less than smallest int232 or\n * greater than largest int232).\n *\n * Counterpart to Solidity's `int232` operator.\n *\n * Requirements:\n *\n * - input must fit into 232 bits\n *\n * _Available since v4.7._\n */\n function toInt232(int256 value) internal pure returns (int232 downcasted) {\n downcasted = int232(value);\n require(downcasted == value, \"SafeCast: value doesn't fit in 232 bits\");\n }\n\n /**\n * @dev Returns the downcasted int224 from int256, reverting on\n * overflow (when the input is less than smallest int224 or\n * greater than largest int224).\n *\n * Counterpart to Solidity's `int224` operator.\n *\n * Requirements:\n *\n * - input must fit into 224 bits\n *\n * _Available since v4.7._\n */\n function toInt224(int256 value) internal pure returns (int224 downcasted) {\n downcasted = int224(value);\n require(downcasted == value, \"SafeCast: value doesn't fit in 224 bits\");\n }\n\n /**\n * @dev Returns the downcasted int216 from int256, reverting on\n * overflow (when the input is less than smallest int216 or\n * greater than largest int216).\n *\n * Counterpart to Solidity's `int216` operator.\n *\n * Requirements:\n *\n * - input must fit into 216 bits\n *\n * _Available since v4.7._\n */\n function toInt216(int256 value) internal pure returns (int216 downcasted) {\n downcasted = int216(value);\n require(downcasted == value, \"SafeCast: value doesn't fit in 216 bits\");\n }\n\n /**\n * @dev Returns the downcasted int208 from int256, reverting on\n * overflow (when the input is less than smallest int208 or\n * greater than largest int208).\n *\n * Counterpart to Solidity's `int208` operator.\n *\n * Requirements:\n *\n * - input must fit into 208 bits\n *\n * _Available since v4.7._\n */\n function toInt208(int256 value) internal pure returns (int208 downcasted) {\n downcasted = int208(value);\n require(downcasted == value, \"SafeCast: value doesn't fit in 208 bits\");\n }\n\n /**\n * @dev Returns the downcasted int200 from int256, reverting on\n * overflow (when the input is less than smallest int200 or\n * greater than largest int200).\n *\n * Counterpart to Solidity's `int200` operator.\n *\n * Requirements:\n *\n * - input must fit into 200 bits\n *\n * _Available since v4.7._\n */\n function toInt200(int256 value) internal pure returns (int200 downcasted) {\n downcasted = int200(value);\n require(downcasted == value, \"SafeCast: value doesn't fit in 200 bits\");\n }\n\n /**\n * @dev Returns the downcasted int192 from int256, reverting on\n * overflow (when the input is less than smallest int192 or\n * greater than largest int192).\n *\n * Counterpart to Solidity's `int192` operator.\n *\n * Requirements:\n *\n * - input must fit into 192 bits\n *\n * _Available since v4.7._\n */\n function toInt192(int256 value) internal pure returns (int192 downcasted) {\n downcasted = int192(value);\n require(downcasted == value, \"SafeCast: value doesn't fit in 192 bits\");\n }\n\n /**\n * @dev Returns the downcasted int184 from int256, reverting on\n * overflow (when the input is less than smallest int184 or\n * greater than largest int184).\n *\n * Counterpart to Solidity's `int184` operator.\n *\n * Requirements:\n *\n * - input must fit into 184 bits\n *\n * _Available since v4.7._\n */\n function toInt184(int256 value) internal pure returns (int184 downcasted) {\n downcasted = int184(value);\n require(downcasted == value, \"SafeCast: value doesn't fit in 184 bits\");\n }\n\n /**\n * @dev Returns the downcasted int176 from int256, reverting on\n * overflow (when the input is less than smallest int176 or\n * greater than largest int176).\n *\n * Counterpart to Solidity's `int176` operator.\n *\n * Requirements:\n *\n * - input must fit into 176 bits\n *\n * _Available since v4.7._\n */\n function toInt176(int256 value) internal pure returns (int176 downcasted) {\n downcasted = int176(value);\n require(downcasted == value, \"SafeCast: value doesn't fit in 176 bits\");\n }\n\n /**\n * @dev Returns the downcasted int168 from int256, reverting on\n * overflow (when the input is less than smallest int168 or\n * greater than largest int168).\n *\n * Counterpart to Solidity's `int168` operator.\n *\n * Requirements:\n *\n * - input must fit into 168 bits\n *\n * _Available since v4.7._\n */\n function toInt168(int256 value) internal pure returns (int168 downcasted) {\n downcasted = int168(value);\n require(downcasted == value, \"SafeCast: value doesn't fit in 168 bits\");\n }\n\n /**\n * @dev Returns the downcasted int160 from int256, reverting on\n * overflow (when the input is less than smallest int160 or\n * greater than largest int160).\n *\n * Counterpart to Solidity's `int160` operator.\n *\n * Requirements:\n *\n * - input must fit into 160 bits\n *\n * _Available since v4.7._\n */\n function toInt160(int256 value) internal pure returns (int160 downcasted) {\n downcasted = int160(value);\n require(downcasted == value, \"SafeCast: value doesn't fit in 160 bits\");\n }\n\n /**\n * @dev Returns the downcasted int152 from int256, reverting on\n * overflow (when the input is less than smallest int152 or\n * greater than largest int152).\n *\n * Counterpart to Solidity's `int152` operator.\n *\n * Requirements:\n *\n * - input must fit into 152 bits\n *\n * _Available since v4.7._\n */\n function toInt152(int256 value) internal pure returns (int152 downcasted) {\n downcasted = int152(value);\n require(downcasted == value, \"SafeCast: value doesn't fit in 152 bits\");\n }\n\n /**\n * @dev Returns the downcasted int144 from int256, reverting on\n * overflow (when the input is less than smallest int144 or\n * greater than largest int144).\n *\n * Counterpart to Solidity's `int144` operator.\n *\n * Requirements:\n *\n * - input must fit into 144 bits\n *\n * _Available since v4.7._\n */\n function toInt144(int256 value) internal pure returns (int144 downcasted) {\n downcasted = int144(value);\n require(downcasted == value, \"SafeCast: value doesn't fit in 144 bits\");\n }\n\n /**\n * @dev Returns the downcasted int136 from int256, reverting on\n * overflow (when the input is less than smallest int136 or\n * greater than largest int136).\n *\n * Counterpart to Solidity's `int136` operator.\n *\n * Requirements:\n *\n * - input must fit into 136 bits\n *\n * _Available since v4.7._\n */\n function toInt136(int256 value) internal pure returns (int136 downcasted) {\n downcasted = int136(value);\n require(downcasted == value, \"SafeCast: value doesn't fit in 136 bits\");\n }\n\n /**\n * @dev Returns the downcasted int128 from int256, reverting on\n * overflow (when the input is less than smallest int128 or\n * greater than largest int128).\n *\n * Counterpart to Solidity's `int128` operator.\n *\n * Requirements:\n *\n * - input must fit into 128 bits\n *\n * _Available since v3.1._\n */\n function toInt128(int256 value) internal pure returns (int128 downcasted) {\n downcasted = int128(value);\n require(downcasted == value, \"SafeCast: value doesn't fit in 128 bits\");\n }\n\n /**\n * @dev Returns the downcasted int120 from int256, reverting on\n * overflow (when the input is less than smallest int120 or\n * greater than largest int120).\n *\n * Counterpart to Solidity's `int120` operator.\n *\n * Requirements:\n *\n * - input must fit into 120 bits\n *\n * _Available since v4.7._\n */\n function toInt120(int256 value) internal pure returns (int120 downcasted) {\n downcasted = int120(value);\n require(downcasted == value, \"SafeCast: value doesn't fit in 120 bits\");\n }\n\n /**\n * @dev Returns the downcasted int112 from int256, reverting on\n * overflow (when the input is less than smallest int112 or\n * greater than largest int112).\n *\n * Counterpart to Solidity's `int112` operator.\n *\n * Requirements:\n *\n * - input must fit into 112 bits\n *\n * _Available since v4.7._\n */\n function toInt112(int256 value) internal pure returns (int112 downcasted) {\n downcasted = int112(value);\n require(downcasted == value, \"SafeCast: value doesn't fit in 112 bits\");\n }\n\n /**\n * @dev Returns the downcasted int104 from int256, reverting on\n * overflow (when the input is less than smallest int104 or\n * greater than largest int104).\n *\n * Counterpart to Solidity's `int104` operator.\n *\n * Requirements:\n *\n * - input must fit into 104 bits\n *\n * _Available since v4.7._\n */\n function toInt104(int256 value) internal pure returns (int104 downcasted) {\n downcasted = int104(value);\n require(downcasted == value, \"SafeCast: value doesn't fit in 104 bits\");\n }\n\n /**\n * @dev Returns the downcasted int96 from int256, reverting on\n * overflow (when the input is less than smallest int96 or\n * greater than largest int96).\n *\n * Counterpart to Solidity's `int96` operator.\n *\n * Requirements:\n *\n * - input must fit into 96 bits\n *\n * _Available since v4.7._\n */\n function toInt96(int256 value) internal pure returns (int96 downcasted) {\n downcasted = int96(value);\n require(downcasted == value, \"SafeCast: value doesn't fit in 96 bits\");\n }\n\n /**\n * @dev Returns the downcasted int88 from int256, reverting on\n * overflow (when the input is less than smallest int88 or\n * greater than largest int88).\n *\n * Counterpart to Solidity's `int88` operator.\n *\n * Requirements:\n *\n * - input must fit into 88 bits\n *\n * _Available since v4.7._\n */\n function toInt88(int256 value) internal pure returns (int88 downcasted) {\n downcasted = int88(value);\n require(downcasted == value, \"SafeCast: value doesn't fit in 88 bits\");\n }\n\n /**\n * @dev Returns the downcasted int80 from int256, reverting on\n * overflow (when the input is less than smallest int80 or\n * greater than largest int80).\n *\n * Counterpart to Solidity's `int80` operator.\n *\n * Requirements:\n *\n * - input must fit into 80 bits\n *\n * _Available since v4.7._\n */\n function toInt80(int256 value) internal pure returns (int80 downcasted) {\n downcasted = int80(value);\n require(downcasted == value, \"SafeCast: value doesn't fit in 80 bits\");\n }\n\n /**\n * @dev Returns the downcasted int72 from int256, reverting on\n * overflow (when the input is less than smallest int72 or\n * greater than largest int72).\n *\n * Counterpart to Solidity's `int72` operator.\n *\n * Requirements:\n *\n * - input must fit into 72 bits\n *\n * _Available since v4.7._\n */\n function toInt72(int256 value) internal pure returns (int72 downcasted) {\n downcasted = int72(value);\n require(downcasted == value, \"SafeCast: value doesn't fit in 72 bits\");\n }\n\n /**\n * @dev Returns the downcasted int64 from int256, reverting on\n * overflow (when the input is less than smallest int64 or\n * greater than largest int64).\n *\n * Counterpart to Solidity's `int64` operator.\n *\n * Requirements:\n *\n * - input must fit into 64 bits\n *\n * _Available since v3.1._\n */\n function toInt64(int256 value) internal pure returns (int64 downcasted) {\n downcasted = int64(value);\n require(downcasted == value, \"SafeCast: value doesn't fit in 64 bits\");\n }\n\n /**\n * @dev Returns the downcasted int56 from int256, reverting on\n * overflow (when the input is less than smallest int56 or\n * greater than largest int56).\n *\n * Counterpart to Solidity's `int56` operator.\n *\n * Requirements:\n *\n * - input must fit into 56 bits\n *\n * _Available since v4.7._\n */\n function toInt56(int256 value) internal pure returns (int56 downcasted) {\n downcasted = int56(value);\n require(downcasted == value, \"SafeCast: value doesn't fit in 56 bits\");\n }\n\n /**\n * @dev Returns the downcasted int48 from int256, reverting on\n * overflow (when the input is less than smallest int48 or\n * greater than largest int48).\n *\n * Counterpart to Solidity's `int48` operator.\n *\n * Requirements:\n *\n * - input must fit into 48 bits\n *\n * _Available since v4.7._\n */\n function toInt48(int256 value) internal pure returns (int48 downcasted) {\n downcasted = int48(value);\n require(downcasted == value, \"SafeCast: value doesn't fit in 48 bits\");\n }\n\n /**\n * @dev Returns the downcasted int40 from int256, reverting on\n * overflow (when the input is less than smallest int40 or\n * greater than largest int40).\n *\n * Counterpart to Solidity's `int40` operator.\n *\n * Requirements:\n *\n * - input must fit into 40 bits\n *\n * _Available since v4.7._\n */\n function toInt40(int256 value) internal pure returns (int40 downcasted) {\n downcasted = int40(value);\n require(downcasted == value, \"SafeCast: value doesn't fit in 40 bits\");\n }\n\n /**\n * @dev Returns the downcasted int32 from int256, reverting on\n * overflow (when the input is less than smallest int32 or\n * greater than largest int32).\n *\n * Counterpart to Solidity's `int32` operator.\n *\n * Requirements:\n *\n * - input must fit into 32 bits\n *\n * _Available since v3.1._\n */\n function toInt32(int256 value) internal pure returns (int32 downcasted) {\n downcasted = int32(value);\n require(downcasted == value, \"SafeCast: value doesn't fit in 32 bits\");\n }\n\n /**\n * @dev Returns the downcasted int24 from int256, reverting on\n * overflow (when the input is less than smallest int24 or\n * greater than largest int24).\n *\n * Counterpart to Solidity's `int24` operator.\n *\n * Requirements:\n *\n * - input must fit into 24 bits\n *\n * _Available since v4.7._\n */\n function toInt24(int256 value) internal pure returns (int24 downcasted) {\n downcasted = int24(value);\n require(downcasted == value, \"SafeCast: value doesn't fit in 24 bits\");\n }\n\n /**\n * @dev Returns the downcasted int16 from int256, reverting on\n * overflow (when the input is less than smallest int16 or\n * greater than largest int16).\n *\n * Counterpart to Solidity's `int16` operator.\n *\n * Requirements:\n *\n * - input must fit into 16 bits\n *\n * _Available since v3.1._\n */\n function toInt16(int256 value) internal pure returns (int16 downcasted) {\n downcasted = int16(value);\n require(downcasted == value, \"SafeCast: value doesn't fit in 16 bits\");\n }\n\n /**\n * @dev Returns the downcasted int8 from int256, reverting on\n * overflow (when the input is less than smallest int8 or\n * greater than largest int8).\n *\n * Counterpart to Solidity's `int8` operator.\n *\n * Requirements:\n *\n * - input must fit into 8 bits\n *\n * _Available since v3.1._\n */\n function toInt8(int256 value) internal pure returns (int8 downcasted) {\n downcasted = int8(value);\n require(downcasted == value, \"SafeCast: value doesn't fit in 8 bits\");\n }\n\n /**\n * @dev Converts an unsigned uint256 into a signed int256.\n *\n * Requirements:\n *\n * - input must be less than or equal to maxInt256.\n *\n * _Available since v3.0._\n */\n function toInt256(uint256 value) internal pure returns (int256) {\n // Note: Unsafe cast below is okay because `type(int256).max` is guaranteed to be positive\n require(value <= uint256(type(int256).max), \"SafeCast: value doesn't fit in an int256\");\n return int256(value);\n }\n}\n" + }, + "@openzeppelin/contracts-upgradeable/utils/StringsUpgradeable.sol": { + "content": "// SPDX-License-Identifier: MIT\n// OpenZeppelin Contracts (last updated v4.8.0) (utils/Strings.sol)\n\npragma solidity ^0.8.0;\n\nimport \"./math/MathUpgradeable.sol\";\n\n/**\n * @dev String operations.\n */\nlibrary StringsUpgradeable {\n bytes16 private constant _SYMBOLS = \"0123456789abcdef\";\n uint8 private constant _ADDRESS_LENGTH = 20;\n\n /**\n * @dev Converts a `uint256` to its ASCII `string` decimal representation.\n */\n function toString(uint256 value) internal pure returns (string memory) {\n unchecked {\n uint256 length = MathUpgradeable.log10(value) + 1;\n string memory buffer = new string(length);\n uint256 ptr;\n /// @solidity memory-safe-assembly\n assembly {\n ptr := add(buffer, add(32, length))\n }\n while (true) {\n ptr--;\n /// @solidity memory-safe-assembly\n assembly {\n mstore8(ptr, byte(mod(value, 10), _SYMBOLS))\n }\n value /= 10;\n if (value == 0) break;\n }\n return buffer;\n }\n }\n\n /**\n * @dev Converts a `uint256` to its ASCII `string` hexadecimal representation.\n */\n function toHexString(uint256 value) internal pure returns (string memory) {\n unchecked {\n return toHexString(value, MathUpgradeable.log256(value) + 1);\n }\n }\n\n /**\n * @dev Converts a `uint256` to its ASCII `string` hexadecimal representation with fixed length.\n */\n function toHexString(uint256 value, uint256 length) internal pure returns (string memory) {\n bytes memory buffer = new bytes(2 * length + 2);\n buffer[0] = \"0\";\n buffer[1] = \"x\";\n for (uint256 i = 2 * length + 1; i > 1; --i) {\n buffer[i] = _SYMBOLS[value & 0xf];\n value >>= 4;\n }\n require(value == 0, \"Strings: hex length insufficient\");\n return string(buffer);\n }\n\n /**\n * @dev Converts an `address` with fixed length of 20 bytes to its not checksummed ASCII `string` hexadecimal representation.\n */\n function toHexString(address addr) internal pure returns (string memory) {\n return toHexString(uint256(uint160(addr)), _ADDRESS_LENGTH);\n }\n}\n" + }, + "@openzeppelin/contracts/access/Ownable.sol": { + "content": "// SPDX-License-Identifier: MIT\n// OpenZeppelin Contracts (last updated v4.7.0) (access/Ownable.sol)\n\npragma solidity ^0.8.0;\n\nimport \"../utils/Context.sol\";\n\n/**\n * @dev Contract module which provides a basic access control mechanism, where\n * there is an account (an owner) that can be granted exclusive access to\n * specific functions.\n *\n * By default, the owner account will be the one that deploys the contract. This\n * can later be changed with {transferOwnership}.\n *\n * This module is used through inheritance. It will make available the modifier\n * `onlyOwner`, which can be applied to your functions to restrict their use to\n * the owner.\n */\nabstract contract Ownable is Context {\n address private _owner;\n\n event OwnershipTransferred(address indexed previousOwner, address indexed newOwner);\n\n /**\n * @dev Initializes the contract setting the deployer as the initial owner.\n */\n constructor() {\n _transferOwnership(_msgSender());\n }\n\n /**\n * @dev Throws if called by any account other than the owner.\n */\n modifier onlyOwner() {\n _checkOwner();\n _;\n }\n\n /**\n * @dev Returns the address of the current owner.\n */\n function owner() public view virtual returns (address) {\n return _owner;\n }\n\n /**\n * @dev Throws if the sender is not the owner.\n */\n function _checkOwner() internal view virtual {\n require(owner() == _msgSender(), \"Ownable: caller is not the owner\");\n }\n\n /**\n * @dev Leaves the contract without owner. It will not be possible to call\n * `onlyOwner` functions anymore. Can only be called by the current owner.\n *\n * NOTE: Renouncing ownership will leave the contract without an owner,\n * thereby removing any functionality that is only available to the owner.\n */\n function renounceOwnership() public virtual onlyOwner {\n _transferOwnership(address(0));\n }\n\n /**\n * @dev Transfers ownership of the contract to a new account (`newOwner`).\n * Can only be called by the current owner.\n */\n function transferOwnership(address newOwner) public virtual onlyOwner {\n require(newOwner != address(0), \"Ownable: new owner is the zero address\");\n _transferOwnership(newOwner);\n }\n\n /**\n * @dev Transfers ownership of the contract to a new account (`newOwner`).\n * Internal function without access restriction.\n */\n function _transferOwnership(address newOwner) internal virtual {\n address oldOwner = _owner;\n _owner = newOwner;\n emit OwnershipTransferred(oldOwner, newOwner);\n }\n}\n" + }, + "@openzeppelin/contracts/interfaces/draft-IERC1822.sol": { + "content": "// SPDX-License-Identifier: MIT\n// OpenZeppelin Contracts (last updated v4.5.0) (interfaces/draft-IERC1822.sol)\n\npragma solidity ^0.8.0;\n\n/**\n * @dev ERC1822: Universal Upgradeable Proxy Standard (UUPS) documents a method for upgradeability through a simplified\n * proxy whose upgrades are fully controlled by the current implementation.\n */\ninterface IERC1822Proxiable {\n /**\n * @dev Returns the storage slot that the proxiable contract assumes is being used to store the implementation\n * address.\n *\n * IMPORTANT: A proxy pointing at a proxiable contract should not be considered proxiable itself, because this risks\n * bricking a proxy that upgrades to it, by delegating to itself until out of gas. Thus it is critical that this\n * function revert if invoked through a proxy.\n */\n function proxiableUUID() external view returns (bytes32);\n}\n" + }, + "@openzeppelin/contracts/proxy/beacon/IBeacon.sol": { + "content": "// SPDX-License-Identifier: MIT\n// OpenZeppelin Contracts v4.4.1 (proxy/beacon/IBeacon.sol)\n\npragma solidity ^0.8.0;\n\n/**\n * @dev This is the interface that {BeaconProxy} expects of its beacon.\n */\ninterface IBeacon {\n /**\n * @dev Must return an address that can be used as a delegate call target.\n *\n * {BeaconProxy} will check that this address is a contract.\n */\n function implementation() external view returns (address);\n}\n" + }, + "@openzeppelin/contracts/proxy/ERC1967/ERC1967Proxy.sol": { + "content": "// SPDX-License-Identifier: MIT\n// OpenZeppelin Contracts (last updated v4.7.0) (proxy/ERC1967/ERC1967Proxy.sol)\n\npragma solidity ^0.8.0;\n\nimport \"../Proxy.sol\";\nimport \"./ERC1967Upgrade.sol\";\n\n/**\n * @dev This contract implements an upgradeable proxy. It is upgradeable because calls are delegated to an\n * implementation address that can be changed. This address is stored in storage in the location specified by\n * https://eips.ethereum.org/EIPS/eip-1967[EIP1967], so that it doesn't conflict with the storage layout of the\n * implementation behind the proxy.\n */\ncontract ERC1967Proxy is Proxy, ERC1967Upgrade {\n /**\n * @dev Initializes the upgradeable proxy with an initial implementation specified by `_logic`.\n *\n * If `_data` is nonempty, it's used as data in a delegate call to `_logic`. This will typically be an encoded\n * function call, and allows initializing the storage of the proxy like a Solidity constructor.\n */\n constructor(address _logic, bytes memory _data) payable {\n _upgradeToAndCall(_logic, _data, false);\n }\n\n /**\n * @dev Returns the current implementation address.\n */\n function _implementation() internal view virtual override returns (address impl) {\n return ERC1967Upgrade._getImplementation();\n }\n}\n" + }, + "@openzeppelin/contracts/proxy/ERC1967/ERC1967Upgrade.sol": { + "content": "// SPDX-License-Identifier: MIT\n// OpenZeppelin Contracts (last updated v4.5.0) (proxy/ERC1967/ERC1967Upgrade.sol)\n\npragma solidity ^0.8.2;\n\nimport \"../beacon/IBeacon.sol\";\nimport \"../../interfaces/draft-IERC1822.sol\";\nimport \"../../utils/Address.sol\";\nimport \"../../utils/StorageSlot.sol\";\n\n/**\n * @dev This abstract contract provides getters and event emitting update functions for\n * https://eips.ethereum.org/EIPS/eip-1967[EIP1967] slots.\n *\n * _Available since v4.1._\n *\n * @custom:oz-upgrades-unsafe-allow delegatecall\n */\nabstract contract ERC1967Upgrade {\n // This is the keccak-256 hash of \"eip1967.proxy.rollback\" subtracted by 1\n bytes32 private constant _ROLLBACK_SLOT = 0x4910fdfa16fed3260ed0e7147f7cc6da11a60208b5b9406d12a635614ffd9143;\n\n /**\n * @dev Storage slot with the address of the current implementation.\n * This is the keccak-256 hash of \"eip1967.proxy.implementation\" subtracted by 1, and is\n * validated in the constructor.\n */\n bytes32 internal constant _IMPLEMENTATION_SLOT = 0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc;\n\n /**\n * @dev Emitted when the implementation is upgraded.\n */\n event Upgraded(address indexed implementation);\n\n /**\n * @dev Returns the current implementation address.\n */\n function _getImplementation() internal view returns (address) {\n return StorageSlot.getAddressSlot(_IMPLEMENTATION_SLOT).value;\n }\n\n /**\n * @dev Stores a new address in the EIP1967 implementation slot.\n */\n function _setImplementation(address newImplementation) private {\n require(Address.isContract(newImplementation), \"ERC1967: new implementation is not a contract\");\n StorageSlot.getAddressSlot(_IMPLEMENTATION_SLOT).value = newImplementation;\n }\n\n /**\n * @dev Perform implementation upgrade\n *\n * Emits an {Upgraded} event.\n */\n function _upgradeTo(address newImplementation) internal {\n _setImplementation(newImplementation);\n emit Upgraded(newImplementation);\n }\n\n /**\n * @dev Perform implementation upgrade with additional setup call.\n *\n * Emits an {Upgraded} event.\n */\n function _upgradeToAndCall(\n address newImplementation,\n bytes memory data,\n bool forceCall\n ) internal {\n _upgradeTo(newImplementation);\n if (data.length > 0 || forceCall) {\n Address.functionDelegateCall(newImplementation, data);\n }\n }\n\n /**\n * @dev Perform implementation upgrade with security checks for UUPS proxies, and additional setup call.\n *\n * Emits an {Upgraded} event.\n */\n function _upgradeToAndCallUUPS(\n address newImplementation,\n bytes memory data,\n bool forceCall\n ) internal {\n // Upgrades from old implementations will perform a rollback test. This test requires the new\n // implementation to upgrade back to the old, non-ERC1822 compliant, implementation. Removing\n // this special case will break upgrade paths from old UUPS implementation to new ones.\n if (StorageSlot.getBooleanSlot(_ROLLBACK_SLOT).value) {\n _setImplementation(newImplementation);\n } else {\n try IERC1822Proxiable(newImplementation).proxiableUUID() returns (bytes32 slot) {\n require(slot == _IMPLEMENTATION_SLOT, \"ERC1967Upgrade: unsupported proxiableUUID\");\n } catch {\n revert(\"ERC1967Upgrade: new implementation is not UUPS\");\n }\n _upgradeToAndCall(newImplementation, data, forceCall);\n }\n }\n\n /**\n * @dev Storage slot with the admin of the contract.\n * This is the keccak-256 hash of \"eip1967.proxy.admin\" subtracted by 1, and is\n * validated in the constructor.\n */\n bytes32 internal constant _ADMIN_SLOT = 0xb53127684a568b3173ae13b9f8a6016e243e63b6e8ee1178d6a717850b5d6103;\n\n /**\n * @dev Emitted when the admin account has changed.\n */\n event AdminChanged(address previousAdmin, address newAdmin);\n\n /**\n * @dev Returns the current admin.\n */\n function _getAdmin() internal view returns (address) {\n return StorageSlot.getAddressSlot(_ADMIN_SLOT).value;\n }\n\n /**\n * @dev Stores a new address in the EIP1967 admin slot.\n */\n function _setAdmin(address newAdmin) private {\n require(newAdmin != address(0), \"ERC1967: new admin is the zero address\");\n StorageSlot.getAddressSlot(_ADMIN_SLOT).value = newAdmin;\n }\n\n /**\n * @dev Changes the admin of the proxy.\n *\n * Emits an {AdminChanged} event.\n */\n function _changeAdmin(address newAdmin) internal {\n emit AdminChanged(_getAdmin(), newAdmin);\n _setAdmin(newAdmin);\n }\n\n /**\n * @dev The storage slot of the UpgradeableBeacon contract which defines the implementation for this proxy.\n * This is bytes32(uint256(keccak256('eip1967.proxy.beacon')) - 1)) and is validated in the constructor.\n */\n bytes32 internal constant _BEACON_SLOT = 0xa3f0ad74e5423aebfd80d3ef4346578335a9a72aeaee59ff6cb3582b35133d50;\n\n /**\n * @dev Emitted when the beacon is upgraded.\n */\n event BeaconUpgraded(address indexed beacon);\n\n /**\n * @dev Returns the current beacon.\n */\n function _getBeacon() internal view returns (address) {\n return StorageSlot.getAddressSlot(_BEACON_SLOT).value;\n }\n\n /**\n * @dev Stores a new beacon in the EIP1967 beacon slot.\n */\n function _setBeacon(address newBeacon) private {\n require(Address.isContract(newBeacon), \"ERC1967: new beacon is not a contract\");\n require(\n Address.isContract(IBeacon(newBeacon).implementation()),\n \"ERC1967: beacon implementation is not a contract\"\n );\n StorageSlot.getAddressSlot(_BEACON_SLOT).value = newBeacon;\n }\n\n /**\n * @dev Perform beacon upgrade with additional setup call. Note: This upgrades the address of the beacon, it does\n * not upgrade the implementation contained in the beacon (see {UpgradeableBeacon-_setImplementation} for that).\n *\n * Emits a {BeaconUpgraded} event.\n */\n function _upgradeBeaconToAndCall(\n address newBeacon,\n bytes memory data,\n bool forceCall\n ) internal {\n _setBeacon(newBeacon);\n emit BeaconUpgraded(newBeacon);\n if (data.length > 0 || forceCall) {\n Address.functionDelegateCall(IBeacon(newBeacon).implementation(), data);\n }\n }\n}\n" + }, + "@openzeppelin/contracts/proxy/Proxy.sol": { + "content": "// SPDX-License-Identifier: MIT\n// OpenZeppelin Contracts (last updated v4.6.0) (proxy/Proxy.sol)\n\npragma solidity ^0.8.0;\n\n/**\n * @dev This abstract contract provides a fallback function that delegates all calls to another contract using the EVM\n * instruction `delegatecall`. We refer to the second contract as the _implementation_ behind the proxy, and it has to\n * be specified by overriding the virtual {_implementation} function.\n *\n * Additionally, delegation to the implementation can be triggered manually through the {_fallback} function, or to a\n * different contract through the {_delegate} function.\n *\n * The success and return data of the delegated call will be returned back to the caller of the proxy.\n */\nabstract contract Proxy {\n /**\n * @dev Delegates the current call to `implementation`.\n *\n * This function does not return to its internal call site, it will return directly to the external caller.\n */\n function _delegate(address implementation) internal virtual {\n assembly {\n // Copy msg.data. We take full control of memory in this inline assembly\n // block because it will not return to Solidity code. We overwrite the\n // Solidity scratch pad at memory position 0.\n calldatacopy(0, 0, calldatasize())\n\n // Call the implementation.\n // out and outsize are 0 because we don't know the size yet.\n let result := delegatecall(gas(), implementation, 0, calldatasize(), 0, 0)\n\n // Copy the returned data.\n returndatacopy(0, 0, returndatasize())\n\n switch result\n // delegatecall returns 0 on error.\n case 0 {\n revert(0, returndatasize())\n }\n default {\n return(0, returndatasize())\n }\n }\n }\n\n /**\n * @dev This is a virtual function that should be overridden so it returns the address to which the fallback function\n * and {_fallback} should delegate.\n */\n function _implementation() internal view virtual returns (address);\n\n /**\n * @dev Delegates the current call to the address returned by `_implementation()`.\n *\n * This function does not return to its internal call site, it will return directly to the external caller.\n */\n function _fallback() internal virtual {\n _beforeFallback();\n _delegate(_implementation());\n }\n\n /**\n * @dev Fallback function that delegates calls to the address returned by `_implementation()`. Will run if no other\n * function in the contract matches the call data.\n */\n fallback() external payable virtual {\n _fallback();\n }\n\n /**\n * @dev Fallback function that delegates calls to the address returned by `_implementation()`. Will run if call data\n * is empty.\n */\n receive() external payable virtual {\n _fallback();\n }\n\n /**\n * @dev Hook that is called before falling back to the implementation. Can happen as part of a manual `_fallback`\n * call, or as part of the Solidity `fallback` or `receive` functions.\n *\n * If overridden should call `super._beforeFallback()`.\n */\n function _beforeFallback() internal virtual {}\n}\n" + }, + "@openzeppelin/contracts/proxy/transparent/ProxyAdmin.sol": { + "content": "// SPDX-License-Identifier: MIT\n// OpenZeppelin Contracts v4.4.1 (proxy/transparent/ProxyAdmin.sol)\n\npragma solidity ^0.8.0;\n\nimport \"./TransparentUpgradeableProxy.sol\";\nimport \"../../access/Ownable.sol\";\n\n/**\n * @dev This is an auxiliary contract meant to be assigned as the admin of a {TransparentUpgradeableProxy}. For an\n * explanation of why you would want to use this see the documentation for {TransparentUpgradeableProxy}.\n */\ncontract ProxyAdmin is Ownable {\n /**\n * @dev Returns the current implementation of `proxy`.\n *\n * Requirements:\n *\n * - This contract must be the admin of `proxy`.\n */\n function getProxyImplementation(TransparentUpgradeableProxy proxy) public view virtual returns (address) {\n // We need to manually run the static call since the getter cannot be flagged as view\n // bytes4(keccak256(\"implementation()\")) == 0x5c60da1b\n (bool success, bytes memory returndata) = address(proxy).staticcall(hex\"5c60da1b\");\n require(success);\n return abi.decode(returndata, (address));\n }\n\n /**\n * @dev Returns the current admin of `proxy`.\n *\n * Requirements:\n *\n * - This contract must be the admin of `proxy`.\n */\n function getProxyAdmin(TransparentUpgradeableProxy proxy) public view virtual returns (address) {\n // We need to manually run the static call since the getter cannot be flagged as view\n // bytes4(keccak256(\"admin()\")) == 0xf851a440\n (bool success, bytes memory returndata) = address(proxy).staticcall(hex\"f851a440\");\n require(success);\n return abi.decode(returndata, (address));\n }\n\n /**\n * @dev Changes the admin of `proxy` to `newAdmin`.\n *\n * Requirements:\n *\n * - This contract must be the current admin of `proxy`.\n */\n function changeProxyAdmin(TransparentUpgradeableProxy proxy, address newAdmin) public virtual onlyOwner {\n proxy.changeAdmin(newAdmin);\n }\n\n /**\n * @dev Upgrades `proxy` to `implementation`. See {TransparentUpgradeableProxy-upgradeTo}.\n *\n * Requirements:\n *\n * - This contract must be the admin of `proxy`.\n */\n function upgrade(TransparentUpgradeableProxy proxy, address implementation) public virtual onlyOwner {\n proxy.upgradeTo(implementation);\n }\n\n /**\n * @dev Upgrades `proxy` to `implementation` and calls a function on the new implementation. See\n * {TransparentUpgradeableProxy-upgradeToAndCall}.\n *\n * Requirements:\n *\n * - This contract must be the admin of `proxy`.\n */\n function upgradeAndCall(\n TransparentUpgradeableProxy proxy,\n address implementation,\n bytes memory data\n ) public payable virtual onlyOwner {\n proxy.upgradeToAndCall{value: msg.value}(implementation, data);\n }\n}\n" + }, + "@openzeppelin/contracts/proxy/transparent/TransparentUpgradeableProxy.sol": { + "content": "// SPDX-License-Identifier: MIT\n// OpenZeppelin Contracts (last updated v4.7.0) (proxy/transparent/TransparentUpgradeableProxy.sol)\n\npragma solidity ^0.8.0;\n\nimport \"../ERC1967/ERC1967Proxy.sol\";\n\n/**\n * @dev This contract implements a proxy that is upgradeable by an admin.\n *\n * To avoid https://medium.com/nomic-labs-blog/malicious-backdoors-in-ethereum-proxies-62629adf3357[proxy selector\n * clashing], which can potentially be used in an attack, this contract uses the\n * https://blog.openzeppelin.com/the-transparent-proxy-pattern/[transparent proxy pattern]. This pattern implies two\n * things that go hand in hand:\n *\n * 1. If any account other than the admin calls the proxy, the call will be forwarded to the implementation, even if\n * that call matches one of the admin functions exposed by the proxy itself.\n * 2. If the admin calls the proxy, it can access the admin functions, but its calls will never be forwarded to the\n * implementation. If the admin tries to call a function on the implementation it will fail with an error that says\n * \"admin cannot fallback to proxy target\".\n *\n * These properties mean that the admin account can only be used for admin actions like upgrading the proxy or changing\n * the admin, so it's best if it's a dedicated account that is not used for anything else. This will avoid headaches due\n * to sudden errors when trying to call a function from the proxy implementation.\n *\n * Our recommendation is for the dedicated account to be an instance of the {ProxyAdmin} contract. If set up this way,\n * you should think of the `ProxyAdmin` instance as the real administrative interface of your proxy.\n */\ncontract TransparentUpgradeableProxy is ERC1967Proxy {\n /**\n * @dev Initializes an upgradeable proxy managed by `_admin`, backed by the implementation at `_logic`, and\n * optionally initialized with `_data` as explained in {ERC1967Proxy-constructor}.\n */\n constructor(\n address _logic,\n address admin_,\n bytes memory _data\n ) payable ERC1967Proxy(_logic, _data) {\n _changeAdmin(admin_);\n }\n\n /**\n * @dev Modifier used internally that will delegate the call to the implementation unless the sender is the admin.\n */\n modifier ifAdmin() {\n if (msg.sender == _getAdmin()) {\n _;\n } else {\n _fallback();\n }\n }\n\n /**\n * @dev Returns the current admin.\n *\n * NOTE: Only the admin can call this function. See {ProxyAdmin-getProxyAdmin}.\n *\n * TIP: To get this value clients can read directly from the storage slot shown below (specified by EIP1967) using the\n * https://eth.wiki/json-rpc/API#eth_getstorageat[`eth_getStorageAt`] RPC call.\n * `0xb53127684a568b3173ae13b9f8a6016e243e63b6e8ee1178d6a717850b5d6103`\n */\n function admin() external ifAdmin returns (address admin_) {\n admin_ = _getAdmin();\n }\n\n /**\n * @dev Returns the current implementation.\n *\n * NOTE: Only the admin can call this function. See {ProxyAdmin-getProxyImplementation}.\n *\n * TIP: To get this value clients can read directly from the storage slot shown below (specified by EIP1967) using the\n * https://eth.wiki/json-rpc/API#eth_getstorageat[`eth_getStorageAt`] RPC call.\n * `0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc`\n */\n function implementation() external ifAdmin returns (address implementation_) {\n implementation_ = _implementation();\n }\n\n /**\n * @dev Changes the admin of the proxy.\n *\n * Emits an {AdminChanged} event.\n *\n * NOTE: Only the admin can call this function. See {ProxyAdmin-changeProxyAdmin}.\n */\n function changeAdmin(address newAdmin) external virtual ifAdmin {\n _changeAdmin(newAdmin);\n }\n\n /**\n * @dev Upgrade the implementation of the proxy.\n *\n * NOTE: Only the admin can call this function. See {ProxyAdmin-upgrade}.\n */\n function upgradeTo(address newImplementation) external ifAdmin {\n _upgradeToAndCall(newImplementation, bytes(\"\"), false);\n }\n\n /**\n * @dev Upgrade the implementation of the proxy, and then call a function from the new implementation as specified\n * by `data`, which should be an encoded function call. This is useful to initialize new storage variables in the\n * proxied contract.\n *\n * NOTE: Only the admin can call this function. See {ProxyAdmin-upgradeAndCall}.\n */\n function upgradeToAndCall(address newImplementation, bytes calldata data) external payable ifAdmin {\n _upgradeToAndCall(newImplementation, data, true);\n }\n\n /**\n * @dev Returns the current admin.\n */\n function _admin() internal view virtual returns (address) {\n return _getAdmin();\n }\n\n /**\n * @dev Makes sure the admin cannot access the fallback function. See {Proxy-_beforeFallback}.\n */\n function _beforeFallback() internal virtual override {\n require(msg.sender != _getAdmin(), \"TransparentUpgradeableProxy: admin cannot fallback to proxy target\");\n super._beforeFallback();\n }\n}\n" + }, + "@openzeppelin/contracts/security/ReentrancyGuard.sol": { + "content": "// SPDX-License-Identifier: MIT\n// OpenZeppelin Contracts (last updated v4.8.0) (security/ReentrancyGuard.sol)\n\npragma solidity ^0.8.0;\n\n/**\n * @dev Contract module that helps prevent reentrant calls to a function.\n *\n * Inheriting from `ReentrancyGuard` will make the {nonReentrant} modifier\n * available, which can be applied to functions to make sure there are no nested\n * (reentrant) calls to them.\n *\n * Note that because there is a single `nonReentrant` guard, functions marked as\n * `nonReentrant` may not call one another. This can be worked around by making\n * those functions `private`, and then adding `external` `nonReentrant` entry\n * points to them.\n *\n * TIP: If you would like to learn more about reentrancy and alternative ways\n * to protect against it, check out our blog post\n * https://blog.openzeppelin.com/reentrancy-after-istanbul/[Reentrancy After Istanbul].\n */\nabstract contract ReentrancyGuard {\n // Booleans are more expensive than uint256 or any type that takes up a full\n // word because each write operation emits an extra SLOAD to first read the\n // slot's contents, replace the bits taken up by the boolean, and then write\n // back. This is the compiler's defense against contract upgrades and\n // pointer aliasing, and it cannot be disabled.\n\n // The values being non-zero value makes deployment a bit more expensive,\n // but in exchange the refund on every call to nonReentrant will be lower in\n // amount. Since refunds are capped to a percentage of the total\n // transaction's gas, it is best to keep them low in cases like this one, to\n // increase the likelihood of the full refund coming into effect.\n uint256 private constant _NOT_ENTERED = 1;\n uint256 private constant _ENTERED = 2;\n\n uint256 private _status;\n\n constructor() {\n _status = _NOT_ENTERED;\n }\n\n /**\n * @dev Prevents a contract from calling itself, directly or indirectly.\n * Calling a `nonReentrant` function from another `nonReentrant`\n * function is not supported. It is possible to prevent this from happening\n * by making the `nonReentrant` function external, and making it call a\n * `private` function that does the actual work.\n */\n modifier nonReentrant() {\n _nonReentrantBefore();\n _;\n _nonReentrantAfter();\n }\n\n function _nonReentrantBefore() private {\n // On the first call to nonReentrant, _status will be _NOT_ENTERED\n require(_status != _ENTERED, \"ReentrancyGuard: reentrant call\");\n\n // Any calls to nonReentrant after this point will fail\n _status = _ENTERED;\n }\n\n function _nonReentrantAfter() private {\n // By storing the original value once again, a refund is triggered (see\n // https://eips.ethereum.org/EIPS/eip-2200)\n _status = _NOT_ENTERED;\n }\n}\n" + }, + "@openzeppelin/contracts/token/ERC20/extensions/draft-IERC20Permit.sol": { + "content": "// SPDX-License-Identifier: MIT\n// OpenZeppelin Contracts v4.4.1 (token/ERC20/extensions/draft-IERC20Permit.sol)\n\npragma solidity ^0.8.0;\n\n/**\n * @dev Interface of the ERC20 Permit extension allowing approvals to be made via signatures, as defined in\n * https://eips.ethereum.org/EIPS/eip-2612[EIP-2612].\n *\n * Adds the {permit} method, which can be used to change an account's ERC20 allowance (see {IERC20-allowance}) by\n * presenting a message signed by the account. By not relying on {IERC20-approve}, the token holder account doesn't\n * need to send a transaction, and thus is not required to hold Ether at all.\n */\ninterface IERC20Permit {\n /**\n * @dev Sets `value` as the allowance of `spender` over ``owner``'s tokens,\n * given ``owner``'s signed approval.\n *\n * IMPORTANT: The same issues {IERC20-approve} has related to transaction\n * ordering also apply here.\n *\n * Emits an {Approval} event.\n *\n * Requirements:\n *\n * - `spender` cannot be the zero address.\n * - `deadline` must be a timestamp in the future.\n * - `v`, `r` and `s` must be a valid `secp256k1` signature from `owner`\n * over the EIP712-formatted function arguments.\n * - the signature must use ``owner``'s current nonce (see {nonces}).\n *\n * For more information on the signature format, see the\n * https://eips.ethereum.org/EIPS/eip-2612#specification[relevant EIP\n * section].\n */\n function permit(\n address owner,\n address spender,\n uint256 value,\n uint256 deadline,\n uint8 v,\n bytes32 r,\n bytes32 s\n ) external;\n\n /**\n * @dev Returns the current nonce for `owner`. This value must be\n * included whenever a signature is generated for {permit}.\n *\n * Every successful call to {permit} increases ``owner``'s nonce by one. This\n * prevents a signature from being used multiple times.\n */\n function nonces(address owner) external view returns (uint256);\n\n /**\n * @dev Returns the domain separator used in the encoding of the signature for {permit}, as defined by {EIP712}.\n */\n // solhint-disable-next-line func-name-mixedcase\n function DOMAIN_SEPARATOR() external view returns (bytes32);\n}\n" + }, + "@openzeppelin/contracts/token/ERC20/extensions/IERC20Metadata.sol": { + "content": "// SPDX-License-Identifier: MIT\n// OpenZeppelin Contracts v4.4.1 (token/ERC20/extensions/IERC20Metadata.sol)\n\npragma solidity ^0.8.0;\n\nimport \"../IERC20.sol\";\n\n/**\n * @dev Interface for the optional metadata functions from the ERC20 standard.\n *\n * _Available since v4.1._\n */\ninterface IERC20Metadata is IERC20 {\n /**\n * @dev Returns the name of the token.\n */\n function name() external view returns (string memory);\n\n /**\n * @dev Returns the symbol of the token.\n */\n function symbol() external view returns (string memory);\n\n /**\n * @dev Returns the decimals places of the token.\n */\n function decimals() external view returns (uint8);\n}\n" + }, + "@openzeppelin/contracts/token/ERC20/IERC20.sol": { + "content": "// SPDX-License-Identifier: MIT\n// OpenZeppelin Contracts (last updated v4.6.0) (token/ERC20/IERC20.sol)\n\npragma solidity ^0.8.0;\n\n/**\n * @dev Interface of the ERC20 standard as defined in the EIP.\n */\ninterface IERC20 {\n /**\n * @dev Emitted when `value` tokens are moved from one account (`from`) to\n * another (`to`).\n *\n * Note that `value` may be zero.\n */\n event Transfer(address indexed from, address indexed to, uint256 value);\n\n /**\n * @dev Emitted when the allowance of a `spender` for an `owner` is set by\n * a call to {approve}. `value` is the new allowance.\n */\n event Approval(address indexed owner, address indexed spender, uint256 value);\n\n /**\n * @dev Returns the amount of tokens in existence.\n */\n function totalSupply() external view returns (uint256);\n\n /**\n * @dev Returns the amount of tokens owned by `account`.\n */\n function balanceOf(address account) external view returns (uint256);\n\n /**\n * @dev Moves `amount` tokens from the caller's account to `to`.\n *\n * Returns a boolean value indicating whether the operation succeeded.\n *\n * Emits a {Transfer} event.\n */\n function transfer(address to, uint256 amount) external returns (bool);\n\n /**\n * @dev Returns the remaining number of tokens that `spender` will be\n * allowed to spend on behalf of `owner` through {transferFrom}. This is\n * zero by default.\n *\n * This value changes when {approve} or {transferFrom} are called.\n */\n function allowance(address owner, address spender) external view returns (uint256);\n\n /**\n * @dev Sets `amount` as the allowance of `spender` over the caller's tokens.\n *\n * Returns a boolean value indicating whether the operation succeeded.\n *\n * IMPORTANT: Beware that changing an allowance with this method brings the risk\n * that someone may use both the old and the new allowance by unfortunate\n * transaction ordering. One possible solution to mitigate this race\n * condition is to first reduce the spender's allowance to 0 and set the\n * desired value afterwards:\n * https://github.com/ethereum/EIPs/issues/20#issuecomment-263524729\n *\n * Emits an {Approval} event.\n */\n function approve(address spender, uint256 amount) external returns (bool);\n\n /**\n * @dev Moves `amount` tokens from `from` to `to` using the\n * allowance mechanism. `amount` is then deducted from the caller's\n * allowance.\n *\n * Returns a boolean value indicating whether the operation succeeded.\n *\n * Emits a {Transfer} event.\n */\n function transferFrom(\n address from,\n address to,\n uint256 amount\n ) external returns (bool);\n}\n" + }, + "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol": { + "content": "// SPDX-License-Identifier: MIT\n// OpenZeppelin Contracts (last updated v4.8.0) (token/ERC20/utils/SafeERC20.sol)\n\npragma solidity ^0.8.0;\n\nimport \"../IERC20.sol\";\nimport \"../extensions/draft-IERC20Permit.sol\";\nimport \"../../../utils/Address.sol\";\n\n/**\n * @title SafeERC20\n * @dev Wrappers around ERC20 operations that throw on failure (when the token\n * contract returns false). Tokens that return no value (and instead revert or\n * throw on failure) are also supported, non-reverting calls are assumed to be\n * successful.\n * To use this library you can add a `using SafeERC20 for IERC20;` statement to your contract,\n * which allows you to call the safe operations as `token.safeTransfer(...)`, etc.\n */\nlibrary SafeERC20 {\n using Address for address;\n\n function safeTransfer(\n IERC20 token,\n address to,\n uint256 value\n ) internal {\n _callOptionalReturn(token, abi.encodeWithSelector(token.transfer.selector, to, value));\n }\n\n function safeTransferFrom(\n IERC20 token,\n address from,\n address to,\n uint256 value\n ) internal {\n _callOptionalReturn(token, abi.encodeWithSelector(token.transferFrom.selector, from, to, value));\n }\n\n /**\n * @dev Deprecated. This function has issues similar to the ones found in\n * {IERC20-approve}, and its usage is discouraged.\n *\n * Whenever possible, use {safeIncreaseAllowance} and\n * {safeDecreaseAllowance} instead.\n */\n function safeApprove(\n IERC20 token,\n address spender,\n uint256 value\n ) internal {\n // safeApprove should only be called when setting an initial allowance,\n // or when resetting it to zero. To increase and decrease it, use\n // 'safeIncreaseAllowance' and 'safeDecreaseAllowance'\n require(\n (value == 0) || (token.allowance(address(this), spender) == 0),\n \"SafeERC20: approve from non-zero to non-zero allowance\"\n );\n _callOptionalReturn(token, abi.encodeWithSelector(token.approve.selector, spender, value));\n }\n\n function safeIncreaseAllowance(\n IERC20 token,\n address spender,\n uint256 value\n ) internal {\n uint256 newAllowance = token.allowance(address(this), spender) + value;\n _callOptionalReturn(token, abi.encodeWithSelector(token.approve.selector, spender, newAllowance));\n }\n\n function safeDecreaseAllowance(\n IERC20 token,\n address spender,\n uint256 value\n ) internal {\n unchecked {\n uint256 oldAllowance = token.allowance(address(this), spender);\n require(oldAllowance >= value, \"SafeERC20: decreased allowance below zero\");\n uint256 newAllowance = oldAllowance - value;\n _callOptionalReturn(token, abi.encodeWithSelector(token.approve.selector, spender, newAllowance));\n }\n }\n\n function safePermit(\n IERC20Permit token,\n address owner,\n address spender,\n uint256 value,\n uint256 deadline,\n uint8 v,\n bytes32 r,\n bytes32 s\n ) internal {\n uint256 nonceBefore = token.nonces(owner);\n token.permit(owner, spender, value, deadline, v, r, s);\n uint256 nonceAfter = token.nonces(owner);\n require(nonceAfter == nonceBefore + 1, \"SafeERC20: permit did not succeed\");\n }\n\n /**\n * @dev Imitates a Solidity high-level call (i.e. a regular function call to a contract), relaxing the requirement\n * on the return value: the return value is optional (but if data is returned, it must not be false).\n * @param token The token targeted by the call.\n * @param data The call data (encoded using abi.encode or one of its variants).\n */\n function _callOptionalReturn(IERC20 token, bytes memory data) private {\n // We need to perform a low level call here, to bypass Solidity's return data size checking mechanism, since\n // we're implementing it ourselves. We use {Address-functionCall} to perform this call, which verifies that\n // the target address contains contract code and also asserts for success in the low-level call.\n\n bytes memory returndata = address(token).functionCall(data, \"SafeERC20: low-level call failed\");\n if (returndata.length > 0) {\n // Return data is optional\n require(abi.decode(returndata, (bool)), \"SafeERC20: ERC20 operation did not succeed\");\n }\n }\n}\n" + }, + "@openzeppelin/contracts/token/ERC721/ERC721.sol": { + "content": "// SPDX-License-Identifier: MIT\n// OpenZeppelin Contracts (last updated v4.8.0) (token/ERC721/ERC721.sol)\n\npragma solidity ^0.8.0;\n\nimport \"./IERC721.sol\";\nimport \"./IERC721Receiver.sol\";\nimport \"./extensions/IERC721Metadata.sol\";\nimport \"../../utils/Address.sol\";\nimport \"../../utils/Context.sol\";\nimport \"../../utils/Strings.sol\";\nimport \"../../utils/introspection/ERC165.sol\";\n\n/**\n * @dev Implementation of https://eips.ethereum.org/EIPS/eip-721[ERC721] Non-Fungible Token Standard, including\n * the Metadata extension, but not including the Enumerable extension, which is available separately as\n * {ERC721Enumerable}.\n */\ncontract ERC721 is Context, ERC165, IERC721, IERC721Metadata {\n using Address for address;\n using Strings for uint256;\n\n // Token name\n string private _name;\n\n // Token symbol\n string private _symbol;\n\n // Mapping from token ID to owner address\n mapping(uint256 => address) private _owners;\n\n // Mapping owner address to token count\n mapping(address => uint256) private _balances;\n\n // Mapping from token ID to approved address\n mapping(uint256 => address) private _tokenApprovals;\n\n // Mapping from owner to operator approvals\n mapping(address => mapping(address => bool)) private _operatorApprovals;\n\n /**\n * @dev Initializes the contract by setting a `name` and a `symbol` to the token collection.\n */\n constructor(string memory name_, string memory symbol_) {\n _name = name_;\n _symbol = symbol_;\n }\n\n /**\n * @dev See {IERC165-supportsInterface}.\n */\n function supportsInterface(bytes4 interfaceId) public view virtual override(ERC165, IERC165) returns (bool) {\n return\n interfaceId == type(IERC721).interfaceId ||\n interfaceId == type(IERC721Metadata).interfaceId ||\n super.supportsInterface(interfaceId);\n }\n\n /**\n * @dev See {IERC721-balanceOf}.\n */\n function balanceOf(address owner) public view virtual override returns (uint256) {\n require(owner != address(0), \"ERC721: address zero is not a valid owner\");\n return _balances[owner];\n }\n\n /**\n * @dev See {IERC721-ownerOf}.\n */\n function ownerOf(uint256 tokenId) public view virtual override returns (address) {\n address owner = _ownerOf(tokenId);\n require(owner != address(0), \"ERC721: invalid token ID\");\n return owner;\n }\n\n /**\n * @dev See {IERC721Metadata-name}.\n */\n function name() public view virtual override returns (string memory) {\n return _name;\n }\n\n /**\n * @dev See {IERC721Metadata-symbol}.\n */\n function symbol() public view virtual override returns (string memory) {\n return _symbol;\n }\n\n /**\n * @dev See {IERC721Metadata-tokenURI}.\n */\n function tokenURI(uint256 tokenId) public view virtual override returns (string memory) {\n _requireMinted(tokenId);\n\n string memory baseURI = _baseURI();\n return bytes(baseURI).length > 0 ? string(abi.encodePacked(baseURI, tokenId.toString())) : \"\";\n }\n\n /**\n * @dev Base URI for computing {tokenURI}. If set, the resulting URI for each\n * token will be the concatenation of the `baseURI` and the `tokenId`. Empty\n * by default, can be overridden in child contracts.\n */\n function _baseURI() internal view virtual returns (string memory) {\n return \"\";\n }\n\n /**\n * @dev See {IERC721-approve}.\n */\n function approve(address to, uint256 tokenId) public virtual override {\n address owner = ERC721.ownerOf(tokenId);\n require(to != owner, \"ERC721: approval to current owner\");\n\n require(\n _msgSender() == owner || isApprovedForAll(owner, _msgSender()),\n \"ERC721: approve caller is not token owner or approved for all\"\n );\n\n _approve(to, tokenId);\n }\n\n /**\n * @dev See {IERC721-getApproved}.\n */\n function getApproved(uint256 tokenId) public view virtual override returns (address) {\n _requireMinted(tokenId);\n\n return _tokenApprovals[tokenId];\n }\n\n /**\n * @dev See {IERC721-setApprovalForAll}.\n */\n function setApprovalForAll(address operator, bool approved) public virtual override {\n _setApprovalForAll(_msgSender(), operator, approved);\n }\n\n /**\n * @dev See {IERC721-isApprovedForAll}.\n */\n function isApprovedForAll(address owner, address operator) public view virtual override returns (bool) {\n return _operatorApprovals[owner][operator];\n }\n\n /**\n * @dev See {IERC721-transferFrom}.\n */\n function transferFrom(\n address from,\n address to,\n uint256 tokenId\n ) public virtual override {\n //solhint-disable-next-line max-line-length\n require(_isApprovedOrOwner(_msgSender(), tokenId), \"ERC721: caller is not token owner or approved\");\n\n _transfer(from, to, tokenId);\n }\n\n /**\n * @dev See {IERC721-safeTransferFrom}.\n */\n function safeTransferFrom(\n address from,\n address to,\n uint256 tokenId\n ) public virtual override {\n safeTransferFrom(from, to, tokenId, \"\");\n }\n\n /**\n * @dev See {IERC721-safeTransferFrom}.\n */\n function safeTransferFrom(\n address from,\n address to,\n uint256 tokenId,\n bytes memory data\n ) public virtual override {\n require(_isApprovedOrOwner(_msgSender(), tokenId), \"ERC721: caller is not token owner or approved\");\n _safeTransfer(from, to, tokenId, data);\n }\n\n /**\n * @dev Safely transfers `tokenId` token from `from` to `to`, checking first that contract recipients\n * are aware of the ERC721 protocol to prevent tokens from being forever locked.\n *\n * `data` is additional data, it has no specified format and it is sent in call to `to`.\n *\n * This internal function is equivalent to {safeTransferFrom}, and can be used to e.g.\n * implement alternative mechanisms to perform token transfer, such as signature-based.\n *\n * Requirements:\n *\n * - `from` cannot be the zero address.\n * - `to` cannot be the zero address.\n * - `tokenId` token must exist and be owned by `from`.\n * - If `to` refers to a smart contract, it must implement {IERC721Receiver-onERC721Received}, which is called upon a safe transfer.\n *\n * Emits a {Transfer} event.\n */\n function _safeTransfer(\n address from,\n address to,\n uint256 tokenId,\n bytes memory data\n ) internal virtual {\n _transfer(from, to, tokenId);\n require(_checkOnERC721Received(from, to, tokenId, data), \"ERC721: transfer to non ERC721Receiver implementer\");\n }\n\n /**\n * @dev Returns the owner of the `tokenId`. Does NOT revert if token doesn't exist\n */\n function _ownerOf(uint256 tokenId) internal view virtual returns (address) {\n return _owners[tokenId];\n }\n\n /**\n * @dev Returns whether `tokenId` exists.\n *\n * Tokens can be managed by their owner or approved accounts via {approve} or {setApprovalForAll}.\n *\n * Tokens start existing when they are minted (`_mint`),\n * and stop existing when they are burned (`_burn`).\n */\n function _exists(uint256 tokenId) internal view virtual returns (bool) {\n return _ownerOf(tokenId) != address(0);\n }\n\n /**\n * @dev Returns whether `spender` is allowed to manage `tokenId`.\n *\n * Requirements:\n *\n * - `tokenId` must exist.\n */\n function _isApprovedOrOwner(address spender, uint256 tokenId) internal view virtual returns (bool) {\n address owner = ERC721.ownerOf(tokenId);\n return (spender == owner || isApprovedForAll(owner, spender) || getApproved(tokenId) == spender);\n }\n\n /**\n * @dev Safely mints `tokenId` and transfers it to `to`.\n *\n * Requirements:\n *\n * - `tokenId` must not exist.\n * - If `to` refers to a smart contract, it must implement {IERC721Receiver-onERC721Received}, which is called upon a safe transfer.\n *\n * Emits a {Transfer} event.\n */\n function _safeMint(address to, uint256 tokenId) internal virtual {\n _safeMint(to, tokenId, \"\");\n }\n\n /**\n * @dev Same as {xref-ERC721-_safeMint-address-uint256-}[`_safeMint`], with an additional `data` parameter which is\n * forwarded in {IERC721Receiver-onERC721Received} to contract recipients.\n */\n function _safeMint(\n address to,\n uint256 tokenId,\n bytes memory data\n ) internal virtual {\n _mint(to, tokenId);\n require(\n _checkOnERC721Received(address(0), to, tokenId, data),\n \"ERC721: transfer to non ERC721Receiver implementer\"\n );\n }\n\n /**\n * @dev Mints `tokenId` and transfers it to `to`.\n *\n * WARNING: Usage of this method is discouraged, use {_safeMint} whenever possible\n *\n * Requirements:\n *\n * - `tokenId` must not exist.\n * - `to` cannot be the zero address.\n *\n * Emits a {Transfer} event.\n */\n function _mint(address to, uint256 tokenId) internal virtual {\n require(to != address(0), \"ERC721: mint to the zero address\");\n require(!_exists(tokenId), \"ERC721: token already minted\");\n\n _beforeTokenTransfer(address(0), to, tokenId, 1);\n\n // Check that tokenId was not minted by `_beforeTokenTransfer` hook\n require(!_exists(tokenId), \"ERC721: token already minted\");\n\n unchecked {\n // Will not overflow unless all 2**256 token ids are minted to the same owner.\n // Given that tokens are minted one by one, it is impossible in practice that\n // this ever happens. Might change if we allow batch minting.\n // The ERC fails to describe this case.\n _balances[to] += 1;\n }\n\n _owners[tokenId] = to;\n\n emit Transfer(address(0), to, tokenId);\n\n _afterTokenTransfer(address(0), to, tokenId, 1);\n }\n\n /**\n * @dev Destroys `tokenId`.\n * The approval is cleared when the token is burned.\n * This is an internal function that does not check if the sender is authorized to operate on the token.\n *\n * Requirements:\n *\n * - `tokenId` must exist.\n *\n * Emits a {Transfer} event.\n */\n function _burn(uint256 tokenId) internal virtual {\n address owner = ERC721.ownerOf(tokenId);\n\n _beforeTokenTransfer(owner, address(0), tokenId, 1);\n\n // Update ownership in case tokenId was transferred by `_beforeTokenTransfer` hook\n owner = ERC721.ownerOf(tokenId);\n\n // Clear approvals\n delete _tokenApprovals[tokenId];\n\n unchecked {\n // Cannot overflow, as that would require more tokens to be burned/transferred\n // out than the owner initially received through minting and transferring in.\n _balances[owner] -= 1;\n }\n delete _owners[tokenId];\n\n emit Transfer(owner, address(0), tokenId);\n\n _afterTokenTransfer(owner, address(0), tokenId, 1);\n }\n\n /**\n * @dev Transfers `tokenId` from `from` to `to`.\n * As opposed to {transferFrom}, this imposes no restrictions on msg.sender.\n *\n * Requirements:\n *\n * - `to` cannot be the zero address.\n * - `tokenId` token must be owned by `from`.\n *\n * Emits a {Transfer} event.\n */\n function _transfer(\n address from,\n address to,\n uint256 tokenId\n ) internal virtual {\n require(ERC721.ownerOf(tokenId) == from, \"ERC721: transfer from incorrect owner\");\n require(to != address(0), \"ERC721: transfer to the zero address\");\n\n _beforeTokenTransfer(from, to, tokenId, 1);\n\n // Check that tokenId was not transferred by `_beforeTokenTransfer` hook\n require(ERC721.ownerOf(tokenId) == from, \"ERC721: transfer from incorrect owner\");\n\n // Clear approvals from the previous owner\n delete _tokenApprovals[tokenId];\n\n unchecked {\n // `_balances[from]` cannot overflow for the same reason as described in `_burn`:\n // `from`'s balance is the number of token held, which is at least one before the current\n // transfer.\n // `_balances[to]` could overflow in the conditions described in `_mint`. That would require\n // all 2**256 token ids to be minted, which in practice is impossible.\n _balances[from] -= 1;\n _balances[to] += 1;\n }\n _owners[tokenId] = to;\n\n emit Transfer(from, to, tokenId);\n\n _afterTokenTransfer(from, to, tokenId, 1);\n }\n\n /**\n * @dev Approve `to` to operate on `tokenId`\n *\n * Emits an {Approval} event.\n */\n function _approve(address to, uint256 tokenId) internal virtual {\n _tokenApprovals[tokenId] = to;\n emit Approval(ERC721.ownerOf(tokenId), to, tokenId);\n }\n\n /**\n * @dev Approve `operator` to operate on all of `owner` tokens\n *\n * Emits an {ApprovalForAll} event.\n */\n function _setApprovalForAll(\n address owner,\n address operator,\n bool approved\n ) internal virtual {\n require(owner != operator, \"ERC721: approve to caller\");\n _operatorApprovals[owner][operator] = approved;\n emit ApprovalForAll(owner, operator, approved);\n }\n\n /**\n * @dev Reverts if the `tokenId` has not been minted yet.\n */\n function _requireMinted(uint256 tokenId) internal view virtual {\n require(_exists(tokenId), \"ERC721: invalid token ID\");\n }\n\n /**\n * @dev Internal function to invoke {IERC721Receiver-onERC721Received} on a target address.\n * The call is not executed if the target address is not a contract.\n *\n * @param from address representing the previous owner of the given token ID\n * @param to target address that will receive the tokens\n * @param tokenId uint256 ID of the token to be transferred\n * @param data bytes optional data to send along with the call\n * @return bool whether the call correctly returned the expected magic value\n */\n function _checkOnERC721Received(\n address from,\n address to,\n uint256 tokenId,\n bytes memory data\n ) private returns (bool) {\n if (to.isContract()) {\n try IERC721Receiver(to).onERC721Received(_msgSender(), from, tokenId, data) returns (bytes4 retval) {\n return retval == IERC721Receiver.onERC721Received.selector;\n } catch (bytes memory reason) {\n if (reason.length == 0) {\n revert(\"ERC721: transfer to non ERC721Receiver implementer\");\n } else {\n /// @solidity memory-safe-assembly\n assembly {\n revert(add(32, reason), mload(reason))\n }\n }\n }\n } else {\n return true;\n }\n }\n\n /**\n * @dev Hook that is called before any token transfer. This includes minting and burning. If {ERC721Consecutive} is\n * used, the hook may be called as part of a consecutive (batch) mint, as indicated by `batchSize` greater than 1.\n *\n * Calling conditions:\n *\n * - When `from` and `to` are both non-zero, ``from``'s tokens will be transferred to `to`.\n * - When `from` is zero, the tokens will be minted for `to`.\n * - When `to` is zero, ``from``'s tokens will be burned.\n * - `from` and `to` are never both zero.\n * - `batchSize` is non-zero.\n *\n * To learn more about hooks, head to xref:ROOT:extending-contracts.adoc#using-hooks[Using Hooks].\n */\n function _beforeTokenTransfer(\n address from,\n address to,\n uint256, /* firstTokenId */\n uint256 batchSize\n ) internal virtual {\n if (batchSize > 1) {\n if (from != address(0)) {\n _balances[from] -= batchSize;\n }\n if (to != address(0)) {\n _balances[to] += batchSize;\n }\n }\n }\n\n /**\n * @dev Hook that is called after any token transfer. This includes minting and burning. If {ERC721Consecutive} is\n * used, the hook may be called as part of a consecutive (batch) mint, as indicated by `batchSize` greater than 1.\n *\n * Calling conditions:\n *\n * - When `from` and `to` are both non-zero, ``from``'s tokens were transferred to `to`.\n * - When `from` is zero, the tokens were minted for `to`.\n * - When `to` is zero, ``from``'s tokens were burned.\n * - `from` and `to` are never both zero.\n * - `batchSize` is non-zero.\n *\n * To learn more about hooks, head to xref:ROOT:extending-contracts.adoc#using-hooks[Using Hooks].\n */\n function _afterTokenTransfer(\n address from,\n address to,\n uint256 firstTokenId,\n uint256 batchSize\n ) internal virtual {}\n}\n" + }, + "@openzeppelin/contracts/token/ERC721/extensions/IERC721Metadata.sol": { + "content": "// SPDX-License-Identifier: MIT\n// OpenZeppelin Contracts v4.4.1 (token/ERC721/extensions/IERC721Metadata.sol)\n\npragma solidity ^0.8.0;\n\nimport \"../IERC721.sol\";\n\n/**\n * @title ERC-721 Non-Fungible Token Standard, optional metadata extension\n * @dev See https://eips.ethereum.org/EIPS/eip-721\n */\ninterface IERC721Metadata is IERC721 {\n /**\n * @dev Returns the token collection name.\n */\n function name() external view returns (string memory);\n\n /**\n * @dev Returns the token collection symbol.\n */\n function symbol() external view returns (string memory);\n\n /**\n * @dev Returns the Uniform Resource Identifier (URI) for `tokenId` token.\n */\n function tokenURI(uint256 tokenId) external view returns (string memory);\n}\n" + }, + "@openzeppelin/contracts/token/ERC721/IERC721.sol": { + "content": "// SPDX-License-Identifier: MIT\n// OpenZeppelin Contracts (last updated v4.8.0) (token/ERC721/IERC721.sol)\n\npragma solidity ^0.8.0;\n\nimport \"../../utils/introspection/IERC165.sol\";\n\n/**\n * @dev Required interface of an ERC721 compliant contract.\n */\ninterface IERC721 is IERC165 {\n /**\n * @dev Emitted when `tokenId` token is transferred from `from` to `to`.\n */\n event Transfer(address indexed from, address indexed to, uint256 indexed tokenId);\n\n /**\n * @dev Emitted when `owner` enables `approved` to manage the `tokenId` token.\n */\n event Approval(address indexed owner, address indexed approved, uint256 indexed tokenId);\n\n /**\n * @dev Emitted when `owner` enables or disables (`approved`) `operator` to manage all of its assets.\n */\n event ApprovalForAll(address indexed owner, address indexed operator, bool approved);\n\n /**\n * @dev Returns the number of tokens in ``owner``'s account.\n */\n function balanceOf(address owner) external view returns (uint256 balance);\n\n /**\n * @dev Returns the owner of the `tokenId` token.\n *\n * Requirements:\n *\n * - `tokenId` must exist.\n */\n function ownerOf(uint256 tokenId) external view returns (address owner);\n\n /**\n * @dev Safely transfers `tokenId` token from `from` to `to`.\n *\n * Requirements:\n *\n * - `from` cannot be the zero address.\n * - `to` cannot be the zero address.\n * - `tokenId` token must exist and be owned by `from`.\n * - If the caller is not `from`, it must be approved to move this token by either {approve} or {setApprovalForAll}.\n * - If `to` refers to a smart contract, it must implement {IERC721Receiver-onERC721Received}, which is called upon a safe transfer.\n *\n * Emits a {Transfer} event.\n */\n function safeTransferFrom(\n address from,\n address to,\n uint256 tokenId,\n bytes calldata data\n ) external;\n\n /**\n * @dev Safely transfers `tokenId` token from `from` to `to`, checking first that contract recipients\n * are aware of the ERC721 protocol to prevent tokens from being forever locked.\n *\n * Requirements:\n *\n * - `from` cannot be the zero address.\n * - `to` cannot be the zero address.\n * - `tokenId` token must exist and be owned by `from`.\n * - If the caller is not `from`, it must have been allowed to move this token by either {approve} or {setApprovalForAll}.\n * - If `to` refers to a smart contract, it must implement {IERC721Receiver-onERC721Received}, which is called upon a safe transfer.\n *\n * Emits a {Transfer} event.\n */\n function safeTransferFrom(\n address from,\n address to,\n uint256 tokenId\n ) external;\n\n /**\n * @dev Transfers `tokenId` token from `from` to `to`.\n *\n * WARNING: Note that the caller is responsible to confirm that the recipient is capable of receiving ERC721\n * or else they may be permanently lost. Usage of {safeTransferFrom} prevents loss, though the caller must\n * understand this adds an external call which potentially creates a reentrancy vulnerability.\n *\n * Requirements:\n *\n * - `from` cannot be the zero address.\n * - `to` cannot be the zero address.\n * - `tokenId` token must be owned by `from`.\n * - If the caller is not `from`, it must be approved to move this token by either {approve} or {setApprovalForAll}.\n *\n * Emits a {Transfer} event.\n */\n function transferFrom(\n address from,\n address to,\n uint256 tokenId\n ) external;\n\n /**\n * @dev Gives permission to `to` to transfer `tokenId` token to another account.\n * The approval is cleared when the token is transferred.\n *\n * Only a single account can be approved at a time, so approving the zero address clears previous approvals.\n *\n * Requirements:\n *\n * - The caller must own the token or be an approved operator.\n * - `tokenId` must exist.\n *\n * Emits an {Approval} event.\n */\n function approve(address to, uint256 tokenId) external;\n\n /**\n * @dev Approve or remove `operator` as an operator for the caller.\n * Operators can call {transferFrom} or {safeTransferFrom} for any token owned by the caller.\n *\n * Requirements:\n *\n * - The `operator` cannot be the caller.\n *\n * Emits an {ApprovalForAll} event.\n */\n function setApprovalForAll(address operator, bool _approved) external;\n\n /**\n * @dev Returns the account approved for `tokenId` token.\n *\n * Requirements:\n *\n * - `tokenId` must exist.\n */\n function getApproved(uint256 tokenId) external view returns (address operator);\n\n /**\n * @dev Returns if the `operator` is allowed to manage all of the assets of `owner`.\n *\n * See {setApprovalForAll}\n */\n function isApprovedForAll(address owner, address operator) external view returns (bool);\n}\n" + }, + "@openzeppelin/contracts/token/ERC721/IERC721Receiver.sol": { + "content": "// SPDX-License-Identifier: MIT\n// OpenZeppelin Contracts (last updated v4.6.0) (token/ERC721/IERC721Receiver.sol)\n\npragma solidity ^0.8.0;\n\n/**\n * @title ERC721 token receiver interface\n * @dev Interface for any contract that wants to support safeTransfers\n * from ERC721 asset contracts.\n */\ninterface IERC721Receiver {\n /**\n * @dev Whenever an {IERC721} `tokenId` token is transferred to this contract via {IERC721-safeTransferFrom}\n * by `operator` from `from`, this function is called.\n *\n * It must return its Solidity selector to confirm the token transfer.\n * If any other value is returned or the interface is not implemented by the recipient, the transfer will be reverted.\n *\n * The selector can be obtained in Solidity with `IERC721Receiver.onERC721Received.selector`.\n */\n function onERC721Received(\n address operator,\n address from,\n uint256 tokenId,\n bytes calldata data\n ) external returns (bytes4);\n}\n" + }, + "@openzeppelin/contracts/utils/Address.sol": { + "content": "// SPDX-License-Identifier: MIT\n// OpenZeppelin Contracts (last updated v4.8.0) (utils/Address.sol)\n\npragma solidity ^0.8.1;\n\n/**\n * @dev Collection of functions related to the address type\n */\nlibrary Address {\n /**\n * @dev Returns true if `account` is a contract.\n *\n * [IMPORTANT]\n * ====\n * It is unsafe to assume that an address for which this function returns\n * false is an externally-owned account (EOA) and not a contract.\n *\n * Among others, `isContract` will return false for the following\n * types of addresses:\n *\n * - an externally-owned account\n * - a contract in construction\n * - an address where a contract will be created\n * - an address where a contract lived, but was destroyed\n * ====\n *\n * [IMPORTANT]\n * ====\n * You shouldn't rely on `isContract` to protect against flash loan attacks!\n *\n * Preventing calls from contracts is highly discouraged. It breaks composability, breaks support for smart wallets\n * like Gnosis Safe, and does not provide security since it can be circumvented by calling from a contract\n * constructor.\n * ====\n */\n function isContract(address account) internal view returns (bool) {\n // This method relies on extcodesize/address.code.length, which returns 0\n // for contracts in construction, since the code is only stored at the end\n // of the constructor execution.\n\n return account.code.length > 0;\n }\n\n /**\n * @dev Replacement for Solidity's `transfer`: sends `amount` wei to\n * `recipient`, forwarding all available gas and reverting on errors.\n *\n * https://eips.ethereum.org/EIPS/eip-1884[EIP1884] increases the gas cost\n * of certain opcodes, possibly making contracts go over the 2300 gas limit\n * imposed by `transfer`, making them unable to receive funds via\n * `transfer`. {sendValue} removes this limitation.\n *\n * https://diligence.consensys.net/posts/2019/09/stop-using-soliditys-transfer-now/[Learn more].\n *\n * IMPORTANT: because control is transferred to `recipient`, care must be\n * taken to not create reentrancy vulnerabilities. Consider using\n * {ReentrancyGuard} or the\n * https://solidity.readthedocs.io/en/v0.5.11/security-considerations.html#use-the-checks-effects-interactions-pattern[checks-effects-interactions pattern].\n */\n function sendValue(address payable recipient, uint256 amount) internal {\n require(address(this).balance >= amount, \"Address: insufficient balance\");\n\n (bool success, ) = recipient.call{value: amount}(\"\");\n require(success, \"Address: unable to send value, recipient may have reverted\");\n }\n\n /**\n * @dev Performs a Solidity function call using a low level `call`. A\n * plain `call` is an unsafe replacement for a function call: use this\n * function instead.\n *\n * If `target` reverts with a revert reason, it is bubbled up by this\n * function (like regular Solidity function calls).\n *\n * Returns the raw returned data. To convert to the expected return value,\n * use https://solidity.readthedocs.io/en/latest/units-and-global-variables.html?highlight=abi.decode#abi-encoding-and-decoding-functions[`abi.decode`].\n *\n * Requirements:\n *\n * - `target` must be a contract.\n * - calling `target` with `data` must not revert.\n *\n * _Available since v3.1._\n */\n function functionCall(address target, bytes memory data) internal returns (bytes memory) {\n return functionCallWithValue(target, data, 0, \"Address: low-level call failed\");\n }\n\n /**\n * @dev Same as {xref-Address-functionCall-address-bytes-}[`functionCall`], but with\n * `errorMessage` as a fallback revert reason when `target` reverts.\n *\n * _Available since v3.1._\n */\n function functionCall(\n address target,\n bytes memory data,\n string memory errorMessage\n ) internal returns (bytes memory) {\n return functionCallWithValue(target, data, 0, errorMessage);\n }\n\n /**\n * @dev Same as {xref-Address-functionCall-address-bytes-}[`functionCall`],\n * but also transferring `value` wei to `target`.\n *\n * Requirements:\n *\n * - the calling contract must have an ETH balance of at least `value`.\n * - the called Solidity function must be `payable`.\n *\n * _Available since v3.1._\n */\n function functionCallWithValue(\n address target,\n bytes memory data,\n uint256 value\n ) internal returns (bytes memory) {\n return functionCallWithValue(target, data, value, \"Address: low-level call with value failed\");\n }\n\n /**\n * @dev Same as {xref-Address-functionCallWithValue-address-bytes-uint256-}[`functionCallWithValue`], but\n * with `errorMessage` as a fallback revert reason when `target` reverts.\n *\n * _Available since v3.1._\n */\n function functionCallWithValue(\n address target,\n bytes memory data,\n uint256 value,\n string memory errorMessage\n ) internal returns (bytes memory) {\n require(address(this).balance >= value, \"Address: insufficient balance for call\");\n (bool success, bytes memory returndata) = target.call{value: value}(data);\n return verifyCallResultFromTarget(target, success, returndata, errorMessage);\n }\n\n /**\n * @dev Same as {xref-Address-functionCall-address-bytes-}[`functionCall`],\n * but performing a static call.\n *\n * _Available since v3.3._\n */\n function functionStaticCall(address target, bytes memory data) internal view returns (bytes memory) {\n return functionStaticCall(target, data, \"Address: low-level static call failed\");\n }\n\n /**\n * @dev Same as {xref-Address-functionCall-address-bytes-string-}[`functionCall`],\n * but performing a static call.\n *\n * _Available since v3.3._\n */\n function functionStaticCall(\n address target,\n bytes memory data,\n string memory errorMessage\n ) internal view returns (bytes memory) {\n (bool success, bytes memory returndata) = target.staticcall(data);\n return verifyCallResultFromTarget(target, success, returndata, errorMessage);\n }\n\n /**\n * @dev Same as {xref-Address-functionCall-address-bytes-}[`functionCall`],\n * but performing a delegate call.\n *\n * _Available since v3.4._\n */\n function functionDelegateCall(address target, bytes memory data) internal returns (bytes memory) {\n return functionDelegateCall(target, data, \"Address: low-level delegate call failed\");\n }\n\n /**\n * @dev Same as {xref-Address-functionCall-address-bytes-string-}[`functionCall`],\n * but performing a delegate call.\n *\n * _Available since v3.4._\n */\n function functionDelegateCall(\n address target,\n bytes memory data,\n string memory errorMessage\n ) internal returns (bytes memory) {\n (bool success, bytes memory returndata) = target.delegatecall(data);\n return verifyCallResultFromTarget(target, success, returndata, errorMessage);\n }\n\n /**\n * @dev Tool to verify that a low level call to smart-contract was successful, and revert (either by bubbling\n * the revert reason or using the provided one) in case of unsuccessful call or if target was not a contract.\n *\n * _Available since v4.8._\n */\n function verifyCallResultFromTarget(\n address target,\n bool success,\n bytes memory returndata,\n string memory errorMessage\n ) internal view returns (bytes memory) {\n if (success) {\n if (returndata.length == 0) {\n // only check isContract if the call was successful and the return data is empty\n // otherwise we already know that it was a contract\n require(isContract(target), \"Address: call to non-contract\");\n }\n return returndata;\n } else {\n _revert(returndata, errorMessage);\n }\n }\n\n /**\n * @dev Tool to verify that a low level call was successful, and revert if it wasn't, either by bubbling the\n * revert reason or using the provided one.\n *\n * _Available since v4.3._\n */\n function verifyCallResult(\n bool success,\n bytes memory returndata,\n string memory errorMessage\n ) internal pure returns (bytes memory) {\n if (success) {\n return returndata;\n } else {\n _revert(returndata, errorMessage);\n }\n }\n\n function _revert(bytes memory returndata, string memory errorMessage) private pure {\n // Look for revert reason and bubble it up if present\n if (returndata.length > 0) {\n // The easiest way to bubble the revert reason is using memory via assembly\n /// @solidity memory-safe-assembly\n assembly {\n let returndata_size := mload(returndata)\n revert(add(32, returndata), returndata_size)\n }\n } else {\n revert(errorMessage);\n }\n }\n}\n" + }, + "@openzeppelin/contracts/utils/Context.sol": { + "content": "// SPDX-License-Identifier: MIT\n// OpenZeppelin Contracts v4.4.1 (utils/Context.sol)\n\npragma solidity ^0.8.0;\n\n/**\n * @dev Provides information about the current execution context, including the\n * sender of the transaction and its data. While these are generally available\n * via msg.sender and msg.data, they should not be accessed in such a direct\n * manner, since when dealing with meta-transactions the account sending and\n * paying for execution may not be the actual sender (as far as an application\n * is concerned).\n *\n * This contract is only required for intermediate, library-like contracts.\n */\nabstract contract Context {\n function _msgSender() internal view virtual returns (address) {\n return msg.sender;\n }\n\n function _msgData() internal view virtual returns (bytes calldata) {\n return msg.data;\n }\n}\n" + }, + "@openzeppelin/contracts/utils/cryptography/ECDSA.sol": { + "content": "// SPDX-License-Identifier: MIT\n// OpenZeppelin Contracts (last updated v4.8.0) (utils/cryptography/ECDSA.sol)\n\npragma solidity ^0.8.0;\n\nimport \"../Strings.sol\";\n\n/**\n * @dev Elliptic Curve Digital Signature Algorithm (ECDSA) operations.\n *\n * These functions can be used to verify that a message was signed by the holder\n * of the private keys of a given address.\n */\nlibrary ECDSA {\n enum RecoverError {\n NoError,\n InvalidSignature,\n InvalidSignatureLength,\n InvalidSignatureS,\n InvalidSignatureV // Deprecated in v4.8\n }\n\n function _throwError(RecoverError error) private pure {\n if (error == RecoverError.NoError) {\n return; // no error: do nothing\n } else if (error == RecoverError.InvalidSignature) {\n revert(\"ECDSA: invalid signature\");\n } else if (error == RecoverError.InvalidSignatureLength) {\n revert(\"ECDSA: invalid signature length\");\n } else if (error == RecoverError.InvalidSignatureS) {\n revert(\"ECDSA: invalid signature 's' value\");\n }\n }\n\n /**\n * @dev Returns the address that signed a hashed message (`hash`) with\n * `signature` or error string. This address can then be used for verification purposes.\n *\n * The `ecrecover` EVM opcode allows for malleable (non-unique) signatures:\n * this function rejects them by requiring the `s` value to be in the lower\n * half order, and the `v` value to be either 27 or 28.\n *\n * IMPORTANT: `hash` _must_ be the result of a hash operation for the\n * verification to be secure: it is possible to craft signatures that\n * recover to arbitrary addresses for non-hashed data. A safe way to ensure\n * this is by receiving a hash of the original message (which may otherwise\n * be too long), and then calling {toEthSignedMessageHash} on it.\n *\n * Documentation for signature generation:\n * - with https://web3js.readthedocs.io/en/v1.3.4/web3-eth-accounts.html#sign[Web3.js]\n * - with https://docs.ethers.io/v5/api/signer/#Signer-signMessage[ethers]\n *\n * _Available since v4.3._\n */\n function tryRecover(bytes32 hash, bytes memory signature) internal pure returns (address, RecoverError) {\n if (signature.length == 65) {\n bytes32 r;\n bytes32 s;\n uint8 v;\n // ecrecover takes the signature parameters, and the only way to get them\n // currently is to use assembly.\n /// @solidity memory-safe-assembly\n assembly {\n r := mload(add(signature, 0x20))\n s := mload(add(signature, 0x40))\n v := byte(0, mload(add(signature, 0x60)))\n }\n return tryRecover(hash, v, r, s);\n } else {\n return (address(0), RecoverError.InvalidSignatureLength);\n }\n }\n\n /**\n * @dev Returns the address that signed a hashed message (`hash`) with\n * `signature`. This address can then be used for verification purposes.\n *\n * The `ecrecover` EVM opcode allows for malleable (non-unique) signatures:\n * this function rejects them by requiring the `s` value to be in the lower\n * half order, and the `v` value to be either 27 or 28.\n *\n * IMPORTANT: `hash` _must_ be the result of a hash operation for the\n * verification to be secure: it is possible to craft signatures that\n * recover to arbitrary addresses for non-hashed data. A safe way to ensure\n * this is by receiving a hash of the original message (which may otherwise\n * be too long), and then calling {toEthSignedMessageHash} on it.\n */\n function recover(bytes32 hash, bytes memory signature) internal pure returns (address) {\n (address recovered, RecoverError error) = tryRecover(hash, signature);\n _throwError(error);\n return recovered;\n }\n\n /**\n * @dev Overload of {ECDSA-tryRecover} that receives the `r` and `vs` short-signature fields separately.\n *\n * See https://eips.ethereum.org/EIPS/eip-2098[EIP-2098 short signatures]\n *\n * _Available since v4.3._\n */\n function tryRecover(\n bytes32 hash,\n bytes32 r,\n bytes32 vs\n ) internal pure returns (address, RecoverError) {\n bytes32 s = vs & bytes32(0x7fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff);\n uint8 v = uint8((uint256(vs) >> 255) + 27);\n return tryRecover(hash, v, r, s);\n }\n\n /**\n * @dev Overload of {ECDSA-recover} that receives the `r and `vs` short-signature fields separately.\n *\n * _Available since v4.2._\n */\n function recover(\n bytes32 hash,\n bytes32 r,\n bytes32 vs\n ) internal pure returns (address) {\n (address recovered, RecoverError error) = tryRecover(hash, r, vs);\n _throwError(error);\n return recovered;\n }\n\n /**\n * @dev Overload of {ECDSA-tryRecover} that receives the `v`,\n * `r` and `s` signature fields separately.\n *\n * _Available since v4.3._\n */\n function tryRecover(\n bytes32 hash,\n uint8 v,\n bytes32 r,\n bytes32 s\n ) internal pure returns (address, RecoverError) {\n // EIP-2 still allows signature malleability for ecrecover(). Remove this possibility and make the signature\n // unique. Appendix F in the Ethereum Yellow paper (https://ethereum.github.io/yellowpaper/paper.pdf), defines\n // the valid range for s in (301): 0 < s < secp256k1n ÷ 2 + 1, and for v in (302): v ∈ {27, 28}. Most\n // signatures from current libraries generate a unique signature with an s-value in the lower half order.\n //\n // If your library generates malleable signatures, such as s-values in the upper range, calculate a new s-value\n // with 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364141 - s1 and flip v from 27 to 28 or\n // vice versa. If your library also generates signatures with 0/1 for v instead 27/28, add 27 to v to accept\n // these malleable signatures as well.\n if (uint256(s) > 0x7FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF5D576E7357A4501DDFE92F46681B20A0) {\n return (address(0), RecoverError.InvalidSignatureS);\n }\n\n // If the signature is valid (and not malleable), return the signer address\n address signer = ecrecover(hash, v, r, s);\n if (signer == address(0)) {\n return (address(0), RecoverError.InvalidSignature);\n }\n\n return (signer, RecoverError.NoError);\n }\n\n /**\n * @dev Overload of {ECDSA-recover} that receives the `v`,\n * `r` and `s` signature fields separately.\n */\n function recover(\n bytes32 hash,\n uint8 v,\n bytes32 r,\n bytes32 s\n ) internal pure returns (address) {\n (address recovered, RecoverError error) = tryRecover(hash, v, r, s);\n _throwError(error);\n return recovered;\n }\n\n /**\n * @dev Returns an Ethereum Signed Message, created from a `hash`. This\n * produces hash corresponding to the one signed with the\n * https://eth.wiki/json-rpc/API#eth_sign[`eth_sign`]\n * JSON-RPC method as part of EIP-191.\n *\n * See {recover}.\n */\n function toEthSignedMessageHash(bytes32 hash) internal pure returns (bytes32) {\n // 32 is the length in bytes of hash,\n // enforced by the type signature above\n return keccak256(abi.encodePacked(\"\\x19Ethereum Signed Message:\\n32\", hash));\n }\n\n /**\n * @dev Returns an Ethereum Signed Message, created from `s`. This\n * produces hash corresponding to the one signed with the\n * https://eth.wiki/json-rpc/API#eth_sign[`eth_sign`]\n * JSON-RPC method as part of EIP-191.\n *\n * See {recover}.\n */\n function toEthSignedMessageHash(bytes memory s) internal pure returns (bytes32) {\n return keccak256(abi.encodePacked(\"\\x19Ethereum Signed Message:\\n\", Strings.toString(s.length), s));\n }\n\n /**\n * @dev Returns an Ethereum Signed Typed Data, created from a\n * `domainSeparator` and a `structHash`. This produces hash corresponding\n * to the one signed with the\n * https://eips.ethereum.org/EIPS/eip-712[`eth_signTypedData`]\n * JSON-RPC method as part of EIP-712.\n *\n * See {recover}.\n */\n function toTypedDataHash(bytes32 domainSeparator, bytes32 structHash) internal pure returns (bytes32) {\n return keccak256(abi.encodePacked(\"\\x19\\x01\", domainSeparator, structHash));\n }\n}\n" + }, + "@openzeppelin/contracts/utils/introspection/ERC165.sol": { + "content": "// SPDX-License-Identifier: MIT\n// OpenZeppelin Contracts v4.4.1 (utils/introspection/ERC165.sol)\n\npragma solidity ^0.8.0;\n\nimport \"./IERC165.sol\";\n\n/**\n * @dev Implementation of the {IERC165} interface.\n *\n * Contracts that want to implement ERC165 should inherit from this contract and override {supportsInterface} to check\n * for the additional interface id that will be supported. For example:\n *\n * ```solidity\n * function supportsInterface(bytes4 interfaceId) public view virtual override returns (bool) {\n * return interfaceId == type(MyInterface).interfaceId || super.supportsInterface(interfaceId);\n * }\n * ```\n *\n * Alternatively, {ERC165Storage} provides an easier to use but more expensive implementation.\n */\nabstract contract ERC165 is IERC165 {\n /**\n * @dev See {IERC165-supportsInterface}.\n */\n function supportsInterface(bytes4 interfaceId) public view virtual override returns (bool) {\n return interfaceId == type(IERC165).interfaceId;\n }\n}\n" + }, + "@openzeppelin/contracts/utils/introspection/IERC165.sol": { + "content": "// SPDX-License-Identifier: MIT\n// OpenZeppelin Contracts v4.4.1 (utils/introspection/IERC165.sol)\n\npragma solidity ^0.8.0;\n\n/**\n * @dev Interface of the ERC165 standard, as defined in the\n * https://eips.ethereum.org/EIPS/eip-165[EIP].\n *\n * Implementers can declare support of contract interfaces, which can then be\n * queried by others ({ERC165Checker}).\n *\n * For an implementation, see {ERC165}.\n */\ninterface IERC165 {\n /**\n * @dev Returns true if this contract implements the interface defined by\n * `interfaceId`. See the corresponding\n * https://eips.ethereum.org/EIPS/eip-165#how-interfaces-are-identified[EIP section]\n * to learn more about how these ids are created.\n *\n * This function call must use less than 30 000 gas.\n */\n function supportsInterface(bytes4 interfaceId) external view returns (bool);\n}\n" + }, + "@openzeppelin/contracts/utils/math/Math.sol": { + "content": "// SPDX-License-Identifier: MIT\n// OpenZeppelin Contracts (last updated v4.8.0) (utils/math/Math.sol)\n\npragma solidity ^0.8.0;\n\n/**\n * @dev Standard math utilities missing in the Solidity language.\n */\nlibrary Math {\n enum Rounding {\n Down, // Toward negative infinity\n Up, // Toward infinity\n Zero // Toward zero\n }\n\n /**\n * @dev Returns the largest of two numbers.\n */\n function max(uint256 a, uint256 b) internal pure returns (uint256) {\n return a > b ? a : b;\n }\n\n /**\n * @dev Returns the smallest of two numbers.\n */\n function min(uint256 a, uint256 b) internal pure returns (uint256) {\n return a < b ? a : b;\n }\n\n /**\n * @dev Returns the average of two numbers. The result is rounded towards\n * zero.\n */\n function average(uint256 a, uint256 b) internal pure returns (uint256) {\n // (a + b) / 2 can overflow.\n return (a & b) + (a ^ b) / 2;\n }\n\n /**\n * @dev Returns the ceiling of the division of two numbers.\n *\n * This differs from standard division with `/` in that it rounds up instead\n * of rounding down.\n */\n function ceilDiv(uint256 a, uint256 b) internal pure returns (uint256) {\n // (a + b - 1) / b can overflow on addition, so we distribute.\n return a == 0 ? 0 : (a - 1) / b + 1;\n }\n\n /**\n * @notice Calculates floor(x * y / denominator) with full precision. Throws if result overflows a uint256 or denominator == 0\n * @dev Original credit to Remco Bloemen under MIT license (https://xn--2-umb.com/21/muldiv)\n * with further edits by Uniswap Labs also under MIT license.\n */\n function mulDiv(\n uint256 x,\n uint256 y,\n uint256 denominator\n ) internal pure returns (uint256 result) {\n unchecked {\n // 512-bit multiply [prod1 prod0] = x * y. Compute the product mod 2^256 and mod 2^256 - 1, then use\n // use the Chinese Remainder Theorem to reconstruct the 512 bit result. The result is stored in two 256\n // variables such that product = prod1 * 2^256 + prod0.\n uint256 prod0; // Least significant 256 bits of the product\n uint256 prod1; // Most significant 256 bits of the product\n assembly {\n let mm := mulmod(x, y, not(0))\n prod0 := mul(x, y)\n prod1 := sub(sub(mm, prod0), lt(mm, prod0))\n }\n\n // Handle non-overflow cases, 256 by 256 division.\n if (prod1 == 0) {\n return prod0 / denominator;\n }\n\n // Make sure the result is less than 2^256. Also prevents denominator == 0.\n require(denominator > prod1);\n\n ///////////////////////////////////////////////\n // 512 by 256 division.\n ///////////////////////////////////////////////\n\n // Make division exact by subtracting the remainder from [prod1 prod0].\n uint256 remainder;\n assembly {\n // Compute remainder using mulmod.\n remainder := mulmod(x, y, denominator)\n\n // Subtract 256 bit number from 512 bit number.\n prod1 := sub(prod1, gt(remainder, prod0))\n prod0 := sub(prod0, remainder)\n }\n\n // Factor powers of two out of denominator and compute largest power of two divisor of denominator. Always >= 1.\n // See https://cs.stackexchange.com/q/138556/92363.\n\n // Does not overflow because the denominator cannot be zero at this stage in the function.\n uint256 twos = denominator & (~denominator + 1);\n assembly {\n // Divide denominator by twos.\n denominator := div(denominator, twos)\n\n // Divide [prod1 prod0] by twos.\n prod0 := div(prod0, twos)\n\n // Flip twos such that it is 2^256 / twos. If twos is zero, then it becomes one.\n twos := add(div(sub(0, twos), twos), 1)\n }\n\n // Shift in bits from prod1 into prod0.\n prod0 |= prod1 * twos;\n\n // Invert denominator mod 2^256. Now that denominator is an odd number, it has an inverse modulo 2^256 such\n // that denominator * inv = 1 mod 2^256. Compute the inverse by starting with a seed that is correct for\n // four bits. That is, denominator * inv = 1 mod 2^4.\n uint256 inverse = (3 * denominator) ^ 2;\n\n // Use the Newton-Raphson iteration to improve the precision. Thanks to Hensel's lifting lemma, this also works\n // in modular arithmetic, doubling the correct bits in each step.\n inverse *= 2 - denominator * inverse; // inverse mod 2^8\n inverse *= 2 - denominator * inverse; // inverse mod 2^16\n inverse *= 2 - denominator * inverse; // inverse mod 2^32\n inverse *= 2 - denominator * inverse; // inverse mod 2^64\n inverse *= 2 - denominator * inverse; // inverse mod 2^128\n inverse *= 2 - denominator * inverse; // inverse mod 2^256\n\n // Because the division is now exact we can divide by multiplying with the modular inverse of denominator.\n // This will give us the correct result modulo 2^256. Since the preconditions guarantee that the outcome is\n // less than 2^256, this is the final result. We don't need to compute the high bits of the result and prod1\n // is no longer required.\n result = prod0 * inverse;\n return result;\n }\n }\n\n /**\n * @notice Calculates x * y / denominator with full precision, following the selected rounding direction.\n */\n function mulDiv(\n uint256 x,\n uint256 y,\n uint256 denominator,\n Rounding rounding\n ) internal pure returns (uint256) {\n uint256 result = mulDiv(x, y, denominator);\n if (rounding == Rounding.Up && mulmod(x, y, denominator) > 0) {\n result += 1;\n }\n return result;\n }\n\n /**\n * @dev Returns the square root of a number. If the number is not a perfect square, the value is rounded down.\n *\n * Inspired by Henry S. Warren, Jr.'s \"Hacker's Delight\" (Chapter 11).\n */\n function sqrt(uint256 a) internal pure returns (uint256) {\n if (a == 0) {\n return 0;\n }\n\n // For our first guess, we get the biggest power of 2 which is smaller than the square root of the target.\n //\n // We know that the \"msb\" (most significant bit) of our target number `a` is a power of 2 such that we have\n // `msb(a) <= a < 2*msb(a)`. This value can be written `msb(a)=2**k` with `k=log2(a)`.\n //\n // This can be rewritten `2**log2(a) <= a < 2**(log2(a) + 1)`\n // → `sqrt(2**k) <= sqrt(a) < sqrt(2**(k+1))`\n // → `2**(k/2) <= sqrt(a) < 2**((k+1)/2) <= 2**(k/2 + 1)`\n //\n // Consequently, `2**(log2(a) / 2)` is a good first approximation of `sqrt(a)` with at least 1 correct bit.\n uint256 result = 1 << (log2(a) >> 1);\n\n // At this point `result` is an estimation with one bit of precision. We know the true value is a uint128,\n // since it is the square root of a uint256. Newton's method converges quadratically (precision doubles at\n // every iteration). We thus need at most 7 iteration to turn our partial result with one bit of precision\n // into the expected uint128 result.\n unchecked {\n result = (result + a / result) >> 1;\n result = (result + a / result) >> 1;\n result = (result + a / result) >> 1;\n result = (result + a / result) >> 1;\n result = (result + a / result) >> 1;\n result = (result + a / result) >> 1;\n result = (result + a / result) >> 1;\n return min(result, a / result);\n }\n }\n\n /**\n * @notice Calculates sqrt(a), following the selected rounding direction.\n */\n function sqrt(uint256 a, Rounding rounding) internal pure returns (uint256) {\n unchecked {\n uint256 result = sqrt(a);\n return result + (rounding == Rounding.Up && result * result < a ? 1 : 0);\n }\n }\n\n /**\n * @dev Return the log in base 2, rounded down, of a positive value.\n * Returns 0 if given 0.\n */\n function log2(uint256 value) internal pure returns (uint256) {\n uint256 result = 0;\n unchecked {\n if (value >> 128 > 0) {\n value >>= 128;\n result += 128;\n }\n if (value >> 64 > 0) {\n value >>= 64;\n result += 64;\n }\n if (value >> 32 > 0) {\n value >>= 32;\n result += 32;\n }\n if (value >> 16 > 0) {\n value >>= 16;\n result += 16;\n }\n if (value >> 8 > 0) {\n value >>= 8;\n result += 8;\n }\n if (value >> 4 > 0) {\n value >>= 4;\n result += 4;\n }\n if (value >> 2 > 0) {\n value >>= 2;\n result += 2;\n }\n if (value >> 1 > 0) {\n result += 1;\n }\n }\n return result;\n }\n\n /**\n * @dev Return the log in base 2, following the selected rounding direction, of a positive value.\n * Returns 0 if given 0.\n */\n function log2(uint256 value, Rounding rounding) internal pure returns (uint256) {\n unchecked {\n uint256 result = log2(value);\n return result + (rounding == Rounding.Up && 1 << result < value ? 1 : 0);\n }\n }\n\n /**\n * @dev Return the log in base 10, rounded down, of a positive value.\n * Returns 0 if given 0.\n */\n function log10(uint256 value) internal pure returns (uint256) {\n uint256 result = 0;\n unchecked {\n if (value >= 10**64) {\n value /= 10**64;\n result += 64;\n }\n if (value >= 10**32) {\n value /= 10**32;\n result += 32;\n }\n if (value >= 10**16) {\n value /= 10**16;\n result += 16;\n }\n if (value >= 10**8) {\n value /= 10**8;\n result += 8;\n }\n if (value >= 10**4) {\n value /= 10**4;\n result += 4;\n }\n if (value >= 10**2) {\n value /= 10**2;\n result += 2;\n }\n if (value >= 10**1) {\n result += 1;\n }\n }\n return result;\n }\n\n /**\n * @dev Return the log in base 10, following the selected rounding direction, of a positive value.\n * Returns 0 if given 0.\n */\n function log10(uint256 value, Rounding rounding) internal pure returns (uint256) {\n unchecked {\n uint256 result = log10(value);\n return result + (rounding == Rounding.Up && 10**result < value ? 1 : 0);\n }\n }\n\n /**\n * @dev Return the log in base 256, rounded down, of a positive value.\n * Returns 0 if given 0.\n *\n * Adding one to the result gives the number of pairs of hex symbols needed to represent `value` as a hex string.\n */\n function log256(uint256 value) internal pure returns (uint256) {\n uint256 result = 0;\n unchecked {\n if (value >> 128 > 0) {\n value >>= 128;\n result += 16;\n }\n if (value >> 64 > 0) {\n value >>= 64;\n result += 8;\n }\n if (value >> 32 > 0) {\n value >>= 32;\n result += 4;\n }\n if (value >> 16 > 0) {\n value >>= 16;\n result += 2;\n }\n if (value >> 8 > 0) {\n result += 1;\n }\n }\n return result;\n }\n\n /**\n * @dev Return the log in base 10, following the selected rounding direction, of a positive value.\n * Returns 0 if given 0.\n */\n function log256(uint256 value, Rounding rounding) internal pure returns (uint256) {\n unchecked {\n uint256 result = log256(value);\n return result + (rounding == Rounding.Up && 1 << (result * 8) < value ? 1 : 0);\n }\n }\n}\n" + }, + "@openzeppelin/contracts/utils/StorageSlot.sol": { + "content": "// SPDX-License-Identifier: MIT\n// OpenZeppelin Contracts (last updated v4.7.0) (utils/StorageSlot.sol)\n\npragma solidity ^0.8.0;\n\n/**\n * @dev Library for reading and writing primitive types to specific storage slots.\n *\n * Storage slots are often used to avoid storage conflict when dealing with upgradeable contracts.\n * This library helps with reading and writing to such slots without the need for inline assembly.\n *\n * The functions in this library return Slot structs that contain a `value` member that can be used to read or write.\n *\n * Example usage to set ERC1967 implementation slot:\n * ```\n * contract ERC1967 {\n * bytes32 internal constant _IMPLEMENTATION_SLOT = 0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc;\n *\n * function _getImplementation() internal view returns (address) {\n * return StorageSlot.getAddressSlot(_IMPLEMENTATION_SLOT).value;\n * }\n *\n * function _setImplementation(address newImplementation) internal {\n * require(Address.isContract(newImplementation), \"ERC1967: new implementation is not a contract\");\n * StorageSlot.getAddressSlot(_IMPLEMENTATION_SLOT).value = newImplementation;\n * }\n * }\n * ```\n *\n * _Available since v4.1 for `address`, `bool`, `bytes32`, and `uint256`._\n */\nlibrary StorageSlot {\n struct AddressSlot {\n address value;\n }\n\n struct BooleanSlot {\n bool value;\n }\n\n struct Bytes32Slot {\n bytes32 value;\n }\n\n struct Uint256Slot {\n uint256 value;\n }\n\n /**\n * @dev Returns an `AddressSlot` with member `value` located at `slot`.\n */\n function getAddressSlot(bytes32 slot) internal pure returns (AddressSlot storage r) {\n /// @solidity memory-safe-assembly\n assembly {\n r.slot := slot\n }\n }\n\n /**\n * @dev Returns an `BooleanSlot` with member `value` located at `slot`.\n */\n function getBooleanSlot(bytes32 slot) internal pure returns (BooleanSlot storage r) {\n /// @solidity memory-safe-assembly\n assembly {\n r.slot := slot\n }\n }\n\n /**\n * @dev Returns an `Bytes32Slot` with member `value` located at `slot`.\n */\n function getBytes32Slot(bytes32 slot) internal pure returns (Bytes32Slot storage r) {\n /// @solidity memory-safe-assembly\n assembly {\n r.slot := slot\n }\n }\n\n /**\n * @dev Returns an `Uint256Slot` with member `value` located at `slot`.\n */\n function getUint256Slot(bytes32 slot) internal pure returns (Uint256Slot storage r) {\n /// @solidity memory-safe-assembly\n assembly {\n r.slot := slot\n }\n }\n}\n" + }, + "@openzeppelin/contracts/utils/Strings.sol": { + "content": "// SPDX-License-Identifier: MIT\n// OpenZeppelin Contracts (last updated v4.8.0) (utils/Strings.sol)\n\npragma solidity ^0.8.0;\n\nimport \"./math/Math.sol\";\n\n/**\n * @dev String operations.\n */\nlibrary Strings {\n bytes16 private constant _SYMBOLS = \"0123456789abcdef\";\n uint8 private constant _ADDRESS_LENGTH = 20;\n\n /**\n * @dev Converts a `uint256` to its ASCII `string` decimal representation.\n */\n function toString(uint256 value) internal pure returns (string memory) {\n unchecked {\n uint256 length = Math.log10(value) + 1;\n string memory buffer = new string(length);\n uint256 ptr;\n /// @solidity memory-safe-assembly\n assembly {\n ptr := add(buffer, add(32, length))\n }\n while (true) {\n ptr--;\n /// @solidity memory-safe-assembly\n assembly {\n mstore8(ptr, byte(mod(value, 10), _SYMBOLS))\n }\n value /= 10;\n if (value == 0) break;\n }\n return buffer;\n }\n }\n\n /**\n * @dev Converts a `uint256` to its ASCII `string` hexadecimal representation.\n */\n function toHexString(uint256 value) internal pure returns (string memory) {\n unchecked {\n return toHexString(value, Math.log256(value) + 1);\n }\n }\n\n /**\n * @dev Converts a `uint256` to its ASCII `string` hexadecimal representation with fixed length.\n */\n function toHexString(uint256 value, uint256 length) internal pure returns (string memory) {\n bytes memory buffer = new bytes(2 * length + 2);\n buffer[0] = \"0\";\n buffer[1] = \"x\";\n for (uint256 i = 2 * length + 1; i > 1; --i) {\n buffer[i] = _SYMBOLS[value & 0xf];\n value >>= 4;\n }\n require(value == 0, \"Strings: hex length insufficient\");\n return string(buffer);\n }\n\n /**\n * @dev Converts an `address` with fixed length of 20 bytes to its not checksummed ASCII `string` hexadecimal representation.\n */\n function toHexString(address addr) internal pure returns (string memory) {\n return toHexString(uint256(uint160(addr)), _ADDRESS_LENGTH);\n }\n}\n" + }, + "@thesis/solidity-contracts/contracts/token/ERC20WithPermit.sol": { + "content": "// SPDX-License-Identifier: MIT\n\npragma solidity ^0.8.4;\n\nimport \"@openzeppelin/contracts/access/Ownable.sol\";\n\nimport \"./IERC20WithPermit.sol\";\nimport \"./IReceiveApproval.sol\";\n\n/// @title ERC20WithPermit\n/// @notice Burnable ERC20 token with EIP2612 permit functionality. User can\n/// authorize a transfer of their token with a signature conforming\n/// EIP712 standard instead of an on-chain transaction from their\n/// address. Anyone can submit this signature on the user's behalf by\n/// calling the permit function, as specified in EIP2612 standard,\n/// paying gas fees, and possibly performing other actions in the same\n/// transaction.\ncontract ERC20WithPermit is IERC20WithPermit, Ownable {\n /// @notice The amount of tokens owned by the given account.\n mapping(address => uint256) public override balanceOf;\n\n /// @notice The remaining number of tokens that spender will be\n /// allowed to spend on behalf of owner through `transferFrom` and\n /// `burnFrom`. This is zero by default.\n mapping(address => mapping(address => uint256)) public override allowance;\n\n /// @notice Returns the current nonce for EIP2612 permission for the\n /// provided token owner for a replay protection. Used to construct\n /// EIP2612 signature provided to `permit` function.\n mapping(address => uint256) public override nonce;\n\n uint256 public immutable cachedChainId;\n bytes32 public immutable cachedDomainSeparator;\n\n /// @notice Returns EIP2612 Permit message hash. Used to construct EIP2612\n /// signature provided to `permit` function.\n bytes32 public constant override PERMIT_TYPEHASH =\n keccak256(\n \"Permit(address owner,address spender,uint256 value,uint256 nonce,uint256 deadline)\"\n );\n\n /// @notice The amount of tokens in existence.\n uint256 public override totalSupply;\n\n /// @notice The name of the token.\n string public override name;\n\n /// @notice The symbol of the token.\n string public override symbol;\n\n /// @notice The decimals places of the token.\n uint8 public constant override decimals = 18;\n\n constructor(string memory _name, string memory _symbol) {\n name = _name;\n symbol = _symbol;\n\n cachedChainId = block.chainid;\n cachedDomainSeparator = buildDomainSeparator();\n }\n\n /// @notice Moves `amount` tokens from the caller's account to `recipient`.\n /// @return True if the operation succeeded, reverts otherwise.\n /// @dev Requirements:\n /// - `recipient` cannot be the zero address,\n /// - the caller must have a balance of at least `amount`.\n function transfer(address recipient, uint256 amount)\n external\n override\n returns (bool)\n {\n _transfer(msg.sender, recipient, amount);\n return true;\n }\n\n /// @notice Moves `amount` tokens from `spender` to `recipient` using the\n /// allowance mechanism. `amount` is then deducted from the caller's\n /// allowance unless the allowance was made for `type(uint256).max`.\n /// @return True if the operation succeeded, reverts otherwise.\n /// @dev Requirements:\n /// - `spender` and `recipient` cannot be the zero address,\n /// - `spender` must have a balance of at least `amount`,\n /// - the caller must have allowance for `spender`'s tokens of at least\n /// `amount`.\n function transferFrom(\n address spender,\n address recipient,\n uint256 amount\n ) external override returns (bool) {\n uint256 currentAllowance = allowance[spender][msg.sender];\n if (currentAllowance != type(uint256).max) {\n require(\n currentAllowance >= amount,\n \"Transfer amount exceeds allowance\"\n );\n _approve(spender, msg.sender, currentAllowance - amount);\n }\n _transfer(spender, recipient, amount);\n return true;\n }\n\n /// @notice EIP2612 approval made with secp256k1 signature.\n /// Users can authorize a transfer of their tokens with a signature\n /// conforming EIP712 standard, rather than an on-chain transaction\n /// from their address. Anyone can submit this signature on the\n /// user's behalf by calling the permit function, paying gas fees,\n /// and possibly performing other actions in the same transaction.\n /// @dev The deadline argument can be set to `type(uint256).max to create\n /// permits that effectively never expire. If the `amount` is set\n /// to `type(uint256).max` then `transferFrom` and `burnFrom` will\n /// not reduce an allowance.\n function permit(\n address owner,\n address spender,\n uint256 amount,\n uint256 deadline,\n uint8 v,\n bytes32 r,\n bytes32 s\n ) external override {\n /* solhint-disable-next-line not-rely-on-time */\n require(deadline >= block.timestamp, \"Permission expired\");\n\n // Validate `s` and `v` values for a malleability concern described in EIP2.\n // Only signatures with `s` value in the lower half of the secp256k1\n // curve's order and `v` value of 27 or 28 are considered valid.\n require(\n uint256(s) <=\n 0x7FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF5D576E7357A4501DDFE92F46681B20A0,\n \"Invalid signature 's' value\"\n );\n require(v == 27 || v == 28, \"Invalid signature 'v' value\");\n\n bytes32 digest = keccak256(\n abi.encodePacked(\n \"\\x19\\x01\",\n DOMAIN_SEPARATOR(),\n keccak256(\n abi.encode(\n PERMIT_TYPEHASH,\n owner,\n spender,\n amount,\n nonce[owner]++,\n deadline\n )\n )\n )\n );\n address recoveredAddress = ecrecover(digest, v, r, s);\n require(\n recoveredAddress != address(0) && recoveredAddress == owner,\n \"Invalid signature\"\n );\n _approve(owner, spender, amount);\n }\n\n /// @notice Creates `amount` tokens and assigns them to `account`,\n /// increasing the total supply.\n /// @dev Requirements:\n /// - `recipient` cannot be the zero address.\n function mint(address recipient, uint256 amount) external onlyOwner {\n require(recipient != address(0), \"Mint to the zero address\");\n\n beforeTokenTransfer(address(0), recipient, amount);\n\n totalSupply += amount;\n balanceOf[recipient] += amount;\n emit Transfer(address(0), recipient, amount);\n }\n\n /// @notice Destroys `amount` tokens from the caller.\n /// @dev Requirements:\n /// - the caller must have a balance of at least `amount`.\n function burn(uint256 amount) external override {\n _burn(msg.sender, amount);\n }\n\n /// @notice Destroys `amount` of tokens from `account` using the allowance\n /// mechanism. `amount` is then deducted from the caller's allowance\n /// unless the allowance was made for `type(uint256).max`.\n /// @dev Requirements:\n /// - `account` must have a balance of at least `amount`,\n /// - the caller must have allowance for `account`'s tokens of at least\n /// `amount`.\n function burnFrom(address account, uint256 amount) external override {\n uint256 currentAllowance = allowance[account][msg.sender];\n if (currentAllowance != type(uint256).max) {\n require(\n currentAllowance >= amount,\n \"Burn amount exceeds allowance\"\n );\n _approve(account, msg.sender, currentAllowance - amount);\n }\n _burn(account, amount);\n }\n\n /// @notice Calls `receiveApproval` function on spender previously approving\n /// the spender to withdraw from the caller multiple times, up to\n /// the `amount` amount. If this function is called again, it\n /// overwrites the current allowance with `amount`. Reverts if the\n /// approval reverted or if `receiveApproval` call on the spender\n /// reverted.\n /// @return True if both approval and `receiveApproval` calls succeeded.\n /// @dev If the `amount` is set to `type(uint256).max` then\n /// `transferFrom` and `burnFrom` will not reduce an allowance.\n function approveAndCall(\n address spender,\n uint256 amount,\n bytes memory extraData\n ) external override returns (bool) {\n if (approve(spender, amount)) {\n IReceiveApproval(spender).receiveApproval(\n msg.sender,\n amount,\n address(this),\n extraData\n );\n return true;\n }\n return false;\n }\n\n /// @notice Sets `amount` as the allowance of `spender` over the caller's\n /// tokens.\n /// @return True if the operation succeeded.\n /// @dev If the `amount` is set to `type(uint256).max` then\n /// `transferFrom` and `burnFrom` will not reduce an allowance.\n /// Beware that changing an allowance with this method brings the risk\n /// that someone may use both the old and the new allowance by\n /// unfortunate transaction ordering. One possible solution to mitigate\n /// this race condition is to first reduce the spender's allowance to 0\n /// and set the desired value afterwards:\n /// https://github.com/ethereum/EIPs/issues/20#issuecomment-263524729\n function approve(address spender, uint256 amount)\n public\n override\n returns (bool)\n {\n _approve(msg.sender, spender, amount);\n return true;\n }\n\n /// @notice Returns hash of EIP712 Domain struct with the token name as\n /// a signing domain and token contract as a verifying contract.\n /// Used to construct EIP2612 signature provided to `permit`\n /// function.\n /* solhint-disable-next-line func-name-mixedcase */\n function DOMAIN_SEPARATOR() public view override returns (bytes32) {\n // As explained in EIP-2612, if the DOMAIN_SEPARATOR contains the\n // chainId and is defined at contract deployment instead of\n // reconstructed for every signature, there is a risk of possible replay\n // attacks between chains in the event of a future chain split.\n // To address this issue, we check the cached chain ID against the\n // current one and in case they are different, we build domain separator\n // from scratch.\n if (block.chainid == cachedChainId) {\n return cachedDomainSeparator;\n } else {\n return buildDomainSeparator();\n }\n }\n\n /// @dev Hook that is called before any transfer of tokens. This includes\n /// minting and burning.\n ///\n /// Calling conditions:\n /// - when `from` and `to` are both non-zero, `amount` of `from`'s tokens\n /// will be to transferred to `to`.\n /// - when `from` is zero, `amount` tokens will be minted for `to`.\n /// - when `to` is zero, `amount` of ``from``'s tokens will be burned.\n /// - `from` and `to` are never both zero.\n // slither-disable-next-line dead-code\n function beforeTokenTransfer(\n address from,\n address to,\n uint256 amount\n ) internal virtual {}\n\n function _burn(address account, uint256 amount) internal {\n uint256 currentBalance = balanceOf[account];\n require(currentBalance >= amount, \"Burn amount exceeds balance\");\n\n beforeTokenTransfer(account, address(0), amount);\n\n balanceOf[account] = currentBalance - amount;\n totalSupply -= amount;\n emit Transfer(account, address(0), amount);\n }\n\n function _transfer(\n address spender,\n address recipient,\n uint256 amount\n ) private {\n require(spender != address(0), \"Transfer from the zero address\");\n require(recipient != address(0), \"Transfer to the zero address\");\n require(recipient != address(this), \"Transfer to the token address\");\n\n beforeTokenTransfer(spender, recipient, amount);\n\n uint256 spenderBalance = balanceOf[spender];\n require(spenderBalance >= amount, \"Transfer amount exceeds balance\");\n balanceOf[spender] = spenderBalance - amount;\n balanceOf[recipient] += amount;\n emit Transfer(spender, recipient, amount);\n }\n\n function _approve(\n address owner,\n address spender,\n uint256 amount\n ) private {\n require(owner != address(0), \"Approve from the zero address\");\n require(spender != address(0), \"Approve to the zero address\");\n allowance[owner][spender] = amount;\n emit Approval(owner, spender, amount);\n }\n\n function buildDomainSeparator() private view returns (bytes32) {\n return\n keccak256(\n abi.encode(\n keccak256(\n \"EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)\"\n ),\n keccak256(bytes(name)),\n keccak256(bytes(\"1\")),\n block.chainid,\n address(this)\n )\n );\n }\n}\n" + }, + "@thesis/solidity-contracts/contracts/token/IApproveAndCall.sol": { + "content": "// SPDX-License-Identifier: MIT\n\npragma solidity ^0.8.4;\n\n/// @notice An interface that should be implemented by tokens supporting\n/// `approveAndCall`/`receiveApproval` pattern.\ninterface IApproveAndCall {\n /// @notice Executes `receiveApproval` function on spender as specified in\n /// `IReceiveApproval` interface. Approves spender to withdraw from\n /// the caller multiple times, up to the `amount`. If this\n /// function is called again, it overwrites the current allowance\n /// with `amount`. Reverts if the approval reverted or if\n /// `receiveApproval` call on the spender reverted.\n function approveAndCall(\n address spender,\n uint256 amount,\n bytes memory extraData\n ) external returns (bool);\n}\n" + }, + "@thesis/solidity-contracts/contracts/token/IERC20WithPermit.sol": { + "content": "// SPDX-License-Identifier: MIT\n\npragma solidity ^0.8.4;\n\nimport \"@openzeppelin/contracts/token/ERC20/IERC20.sol\";\nimport \"@openzeppelin/contracts/token/ERC20/extensions/IERC20Metadata.sol\";\n\nimport \"./IApproveAndCall.sol\";\n\n/// @title IERC20WithPermit\n/// @notice Burnable ERC20 token with EIP2612 permit functionality. User can\n/// authorize a transfer of their token with a signature conforming\n/// EIP712 standard instead of an on-chain transaction from their\n/// address. Anyone can submit this signature on the user's behalf by\n/// calling the permit function, as specified in EIP2612 standard,\n/// paying gas fees, and possibly performing other actions in the same\n/// transaction.\ninterface IERC20WithPermit is IERC20, IERC20Metadata, IApproveAndCall {\n /// @notice EIP2612 approval made with secp256k1 signature.\n /// Users can authorize a transfer of their tokens with a signature\n /// conforming EIP712 standard, rather than an on-chain transaction\n /// from their address. Anyone can submit this signature on the\n /// user's behalf by calling the permit function, paying gas fees,\n /// and possibly performing other actions in the same transaction.\n /// @dev The deadline argument can be set to `type(uint256).max to create\n /// permits that effectively never expire.\n function permit(\n address owner,\n address spender,\n uint256 amount,\n uint256 deadline,\n uint8 v,\n bytes32 r,\n bytes32 s\n ) external;\n\n /// @notice Destroys `amount` tokens from the caller.\n function burn(uint256 amount) external;\n\n /// @notice Destroys `amount` of tokens from `account`, deducting the amount\n /// from caller's allowance.\n function burnFrom(address account, uint256 amount) external;\n\n /// @notice Returns hash of EIP712 Domain struct with the token name as\n /// a signing domain and token contract as a verifying contract.\n /// Used to construct EIP2612 signature provided to `permit`\n /// function.\n /* solhint-disable-next-line func-name-mixedcase */\n function DOMAIN_SEPARATOR() external view returns (bytes32);\n\n /// @notice Returns the current nonce for EIP2612 permission for the\n /// provided token owner for a replay protection. Used to construct\n /// EIP2612 signature provided to `permit` function.\n function nonce(address owner) external view returns (uint256);\n\n /// @notice Returns EIP2612 Permit message hash. Used to construct EIP2612\n /// signature provided to `permit` function.\n /* solhint-disable-next-line func-name-mixedcase */\n function PERMIT_TYPEHASH() external pure returns (bytes32);\n}\n" + }, + "@thesis/solidity-contracts/contracts/token/IReceiveApproval.sol": { + "content": "// SPDX-License-Identifier: MIT\n\npragma solidity ^0.8.4;\n\n/// @notice An interface that should be implemented by contracts supporting\n/// `approveAndCall`/`receiveApproval` pattern.\ninterface IReceiveApproval {\n /// @notice Receives approval to spend tokens. Called as a result of\n /// `approveAndCall` call on the token.\n function receiveApproval(\n address from,\n uint256 amount,\n address token,\n bytes calldata extraData\n ) external;\n}\n" + }, + "@thesis/solidity-contracts/contracts/token/MisfundRecovery.sol": { + "content": "// SPDX-License-Identifier: MIT\n\npragma solidity ^0.8.4;\n\nimport \"@openzeppelin/contracts/access/Ownable.sol\";\nimport \"@openzeppelin/contracts/token/ERC20/IERC20.sol\";\nimport \"@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol\";\nimport \"@openzeppelin/contracts/token/ERC721/IERC721.sol\";\n\n/// @title MisfundRecovery\n/// @notice Allows the owner of the token contract extending MisfundRecovery\n/// to recover any ERC20 and ERC721 sent mistakenly to the token\n/// contract address.\ncontract MisfundRecovery is Ownable {\n using SafeERC20 for IERC20;\n\n function recoverERC20(\n IERC20 token,\n address recipient,\n uint256 amount\n ) external onlyOwner {\n token.safeTransfer(recipient, amount);\n }\n\n function recoverERC721(\n IERC721 token,\n address recipient,\n uint256 tokenId,\n bytes calldata data\n ) external onlyOwner {\n token.safeTransferFrom(address(this), recipient, tokenId, data);\n }\n}\n" + }, + "@threshold-network/solidity-contracts/contracts/staking/IApplication.sol": { + "content": "// SPDX-License-Identifier: GPL-3.0-or-later\n\n// ██████████████ ▐████▌ ██████████████\n// ██████████████ ▐████▌ ██████████████\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ██████████████ ▐████▌ ██████████████\n// ██████████████ ▐████▌ ██████████████\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n\npragma solidity ^0.8.9;\n\n/// @title Application interface for Threshold Network applications\n/// @notice Generic interface for an application. Application is an external\n/// smart contract or a set of smart contracts utilizing functionalities\n/// offered by Threshold Network. Applications authorized for the given\n/// staking provider are eligible to slash the stake delegated to that\n/// staking provider.\ninterface IApplication {\n /// @dev Event emitted by `withdrawRewards` function.\n event RewardsWithdrawn(address indexed stakingProvider, uint96 amount);\n\n /// @notice Withdraws application rewards for the given staking provider.\n /// Rewards are withdrawn to the staking provider's beneficiary\n /// address set in the staking contract.\n /// @dev Emits `RewardsWithdrawn` event.\n function withdrawRewards(address stakingProvider) external;\n\n /// @notice Used by T staking contract to inform the application that the\n /// authorized amount for the given staking provider increased.\n /// The application may do any necessary housekeeping. The\n /// application must revert the transaction in case the\n /// authorization is below the minimum required.\n function authorizationIncreased(\n address stakingProvider,\n uint96 fromAmount,\n uint96 toAmount\n ) external;\n\n /// @notice Used by T staking contract to inform the application that the\n /// authorization decrease for the given staking provider has been\n /// requested. The application should mark the authorization as\n /// pending decrease and respond to the staking contract with\n /// `approveAuthorizationDecrease` at its discretion. It may\n /// happen right away but it also may happen several months later.\n /// If there is already a pending authorization decrease request\n /// for the application, and the application does not agree for\n /// overwriting it, the function should revert.\n function authorizationDecreaseRequested(\n address stakingProvider,\n uint96 fromAmount,\n uint96 toAmount\n ) external;\n\n /// @notice Used by T staking contract to inform the application the\n /// authorization has been decreased for the given staking provider\n /// involuntarily, as a result of slashing. Lets the application to\n /// do any housekeeping neccessary. Called with 250k gas limit and\n /// does not revert the transaction if\n /// `involuntaryAuthorizationDecrease` call failed.\n function involuntaryAuthorizationDecrease(\n address stakingProvider,\n uint96 fromAmount,\n uint96 toAmount\n ) external;\n\n /// @notice Returns the amount of application rewards available for\n /// withdrawal for the given staking provider.\n function availableRewards(address stakingProvider)\n external\n view\n returns (uint96);\n\n /// @notice The minimum authorization amount required for the staking\n /// provider so that they can participate in the application.\n function minimumAuthorization() external view returns (uint96);\n}\n" + }, + "@threshold-network/solidity-contracts/contracts/staking/IStaking.sol": { + "content": "// SPDX-License-Identifier: GPL-3.0-or-later\n\n// ██████████████ ▐████▌ ██████████████\n// ██████████████ ▐████▌ ██████████████\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ██████████████ ▐████▌ ██████████████\n// ██████████████ ▐████▌ ██████████████\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n\npragma solidity ^0.8.9;\n\n/// @title Interface of Threshold Network staking contract\n/// @notice The staking contract enables T owners to have their wallets offline\n/// and their stake managed by staking providers on their behalf.\n/// The staking contract does not define operator role. The operator\n/// responsible for running off-chain client software is appointed by\n/// the staking provider in the particular application utilizing the\n/// staking contract. All off-chain client software should be able\n/// to run without exposing operator's or staking provider’s private\n/// key and should not require any owner’s keys at all. The stake\n/// delegation optimizes the network throughput without compromising the\n/// security of the owners’ stake.\ninterface IStaking {\n enum StakeType {\n NU,\n KEEP,\n T\n }\n\n //\n //\n // Delegating a stake\n //\n //\n\n /// @notice Creates a delegation with `msg.sender` owner with the given\n /// staking provider, beneficiary, and authorizer. Transfers the\n /// given amount of T to the staking contract.\n /// @dev The owner of the delegation needs to have the amount approved to\n /// transfer to the staking contract.\n function stake(\n address stakingProvider,\n address payable beneficiary,\n address authorizer,\n uint96 amount\n ) external;\n\n /// @notice Copies delegation from the legacy KEEP staking contract to T\n /// staking contract. No tokens are transferred. Caches the active\n /// stake amount from KEEP staking contract. Can be called by\n /// anyone.\n /// @dev The staking provider in T staking contract is the legacy KEEP\n /// staking contract operator.\n function stakeKeep(address stakingProvider) external;\n\n /// @notice Copies delegation from the legacy NU staking contract to T\n /// staking contract, additionally appointing staking provider,\n /// beneficiary and authorizer roles. Caches the amount staked in NU\n /// staking contract. Can be called only by the original delegation\n /// owner.\n function stakeNu(\n address stakingProvider,\n address payable beneficiary,\n address authorizer\n ) external;\n\n /// @notice Refresh Keep stake owner. Can be called only by the old owner\n /// or their staking provider.\n /// @dev The staking provider in T staking contract is the legacy KEEP\n /// staking contract operator.\n function refreshKeepStakeOwner(address stakingProvider) external;\n\n /// @notice Allows the Governance to set the minimum required stake amount.\n /// This amount is required to protect against griefing the staking\n /// contract and individual applications are allowed to require\n /// higher minimum stakes if necessary.\n function setMinimumStakeAmount(uint96 amount) external;\n\n //\n //\n // Authorizing an application\n //\n //\n\n /// @notice Allows the Governance to approve the particular application\n /// before individual stake authorizers are able to authorize it.\n function approveApplication(address application) external;\n\n /// @notice Increases the authorization of the given staking provider for\n /// the given application by the given amount. Can only be called by\n /// the authorizer for that staking provider.\n /// @dev Calls `authorizationIncreased(address stakingProvider, uint256 amount)`\n /// on the given application to notify the application about\n /// authorization change. See `IApplication`.\n function increaseAuthorization(\n address stakingProvider,\n address application,\n uint96 amount\n ) external;\n\n /// @notice Requests decrease of the authorization for the given staking\n /// provider on the given application by the provided amount.\n /// It may not change the authorized amount immediatelly. When\n /// it happens depends on the application. Can only be called by the\n /// given staking provider’s authorizer. Overwrites pending\n /// authorization decrease for the given staking provider and\n /// application if the application agrees for that. If the\n /// application does not agree for overwriting, the function\n /// reverts.\n /// @dev Calls `authorizationDecreaseRequested(address stakingProvider, uint256 amount)`\n /// on the given application. See `IApplication`.\n function requestAuthorizationDecrease(\n address stakingProvider,\n address application,\n uint96 amount\n ) external;\n\n /// @notice Requests decrease of all authorizations for the given staking\n /// provider on all applications by all authorized amount.\n /// It may not change the authorized amount immediatelly. When\n /// it happens depends on the application. Can only be called by the\n /// given staking provider’s authorizer. Overwrites pending\n /// authorization decrease for the given staking provider and\n /// application.\n /// @dev Calls `authorizationDecreaseRequested(address stakingProvider, uint256 amount)`\n /// for each authorized application. See `IApplication`.\n function requestAuthorizationDecrease(address stakingProvider) external;\n\n /// @notice Called by the application at its discretion to approve the\n /// previously requested authorization decrease request. Can only be\n /// called by the application that was previously requested to\n /// decrease the authorization for that staking provider.\n /// Returns resulting authorized amount for the application.\n function approveAuthorizationDecrease(address stakingProvider)\n external\n returns (uint96);\n\n /// @notice Decreases the authorization for the given `stakingProvider` on\n /// the given disabled `application`, for all authorized amount.\n /// Can be called by anyone.\n function forceDecreaseAuthorization(\n address stakingProvider,\n address application\n ) external;\n\n /// @notice Pauses the given application’s eligibility to slash stakes.\n /// Besides that stakers can't change authorization to the application.\n /// Can be called only by the Panic Button of the particular\n /// application. The paused application can not slash stakes until\n /// it is approved again by the Governance using `approveApplication`\n /// function. Should be used only in case of an emergency.\n function pauseApplication(address application) external;\n\n /// @notice Disables the given application. The disabled application can't\n /// slash stakers. Also stakers can't increase authorization to that\n /// application but can decrease without waiting by calling\n /// `requestAuthorizationDecrease` at any moment. Can be called only\n /// by the governance. The disabled application can't be approved\n /// again. Should be used only in case of an emergency.\n function disableApplication(address application) external;\n\n /// @notice Sets the Panic Button role for the given application to the\n /// provided address. Can only be called by the Governance. If the\n /// Panic Button for the given application should be disabled, the\n /// role address should be set to 0x0 address.\n function setPanicButton(address application, address panicButton) external;\n\n /// @notice Sets the maximum number of applications one staking provider can\n /// have authorized. Used to protect against DoSing slashing queue.\n /// Can only be called by the Governance.\n function setAuthorizationCeiling(uint256 ceiling) external;\n\n //\n //\n // Stake top-up\n //\n //\n\n /// @notice Increases the amount of the stake for the given staking provider.\n /// @dev The sender of this transaction needs to have the amount approved to\n /// transfer to the staking contract.\n function topUp(address stakingProvider, uint96 amount) external;\n\n /// @notice Propagates information about stake top-up from the legacy KEEP\n /// staking contract to T staking contract. Can be called only by\n /// the owner or the staking provider.\n function topUpKeep(address stakingProvider) external;\n\n /// @notice Propagates information about stake top-up from the legacy NU\n /// staking contract to T staking contract. Can be called only by\n /// the owner or the staking provider.\n function topUpNu(address stakingProvider) external;\n\n //\n //\n // Undelegating a stake (unstaking)\n //\n //\n\n /// @notice Reduces the liquid T stake amount by the provided amount and\n /// withdraws T to the owner. Reverts if there is at least one\n /// authorization higher than the sum of the legacy stake and\n /// remaining liquid T stake or if the unstake amount is higher than\n /// the liquid T stake amount. Can be called only by the delegation\n /// owner or the staking provider.\n function unstakeT(address stakingProvider, uint96 amount) external;\n\n /// @notice Sets the legacy KEEP staking contract active stake amount cached\n /// in T staking contract to 0. Reverts if the amount of liquid T\n /// staked in T staking contract is lower than the highest\n /// application authorization. This function allows to unstake from\n /// KEEP staking contract and still being able to operate in T\n /// network and earning rewards based on the liquid T staked. Can be\n /// called only by the delegation owner or the staking provider.\n function unstakeKeep(address stakingProvider) external;\n\n /// @notice Reduces cached legacy NU stake amount by the provided amount.\n /// Reverts if there is at least one authorization higher than the\n /// sum of remaining legacy NU stake and liquid T stake for that\n /// staking provider or if the untaked amount is higher than the\n /// cached legacy stake amount. If succeeded, the legacy NU stake\n /// can be partially or fully undelegated on the legacy staking\n /// contract. This function allows to unstake from NU staking\n /// contract and still being able to operate in T network and\n /// earning rewards based on the liquid T staked. Can be called only\n /// by the delegation owner or the staking provider.\n function unstakeNu(address stakingProvider, uint96 amount) external;\n\n /// @notice Sets cached legacy stake amount to 0, sets the liquid T stake\n /// amount to 0 and withdraws all liquid T from the stake to the\n /// owner. Reverts if there is at least one non-zero authorization.\n /// Can be called only by the delegation owner or the staking\n /// provider.\n function unstakeAll(address stakingProvider) external;\n\n //\n //\n // Keeping information in sync\n //\n //\n\n /// @notice Notifies about the discrepancy between legacy KEEP active stake\n /// and the amount cached in T staking contract. Slashes the staking\n /// provider in case the amount cached is higher than the actual\n /// active stake amount in KEEP staking contract. Needs to update\n /// authorizations of all affected applications and execute an\n /// involuntary allocation decrease on all affected applications.\n /// Can be called by anyone, notifier receives a reward.\n function notifyKeepStakeDiscrepancy(address stakingProvider) external;\n\n /// @notice Notifies about the discrepancy between legacy NU active stake\n /// and the amount cached in T staking contract. Slashes the\n /// staking provider in case the amount cached is higher than the\n /// actual active stake amount in NU staking contract. Needs to\n /// update authorizations of all affected applications and execute\n /// an involuntary allocation decrease on all affected applications.\n /// Can be called by anyone, notifier receives a reward.\n function notifyNuStakeDiscrepancy(address stakingProvider) external;\n\n /// @notice Sets the penalty amount for stake discrepancy and reward\n /// multiplier for reporting it. The penalty is seized from the\n /// delegated stake, and 5% of the penalty, scaled by the\n /// multiplier, is given to the notifier. The rest of the tokens are\n /// burned. Can only be called by the Governance. See `seize` function.\n function setStakeDiscrepancyPenalty(\n uint96 penalty,\n uint256 rewardMultiplier\n ) external;\n\n /// @notice Sets reward in T tokens for notification of misbehaviour\n /// of one staking provider. Can only be called by the governance.\n function setNotificationReward(uint96 reward) external;\n\n /// @notice Transfer some amount of T tokens as reward for notifications\n /// of misbehaviour\n function pushNotificationReward(uint96 reward) external;\n\n /// @notice Withdraw some amount of T tokens from notifiers treasury.\n /// Can only be called by the governance.\n function withdrawNotificationReward(address recipient, uint96 amount)\n external;\n\n /// @notice Adds staking providers to the slashing queue along with the\n /// amount that should be slashed from each one of them. Can only be\n /// called by application authorized for all staking providers in\n /// the array.\n function slash(uint96 amount, address[] memory stakingProviders) external;\n\n /// @notice Adds staking providers to the slashing queue along with the\n /// amount. The notifier will receive reward per each staking\n /// provider from notifiers treasury. Can only be called by\n /// application authorized for all staking providers in the array.\n function seize(\n uint96 amount,\n uint256 rewardMultipier,\n address notifier,\n address[] memory stakingProviders\n ) external;\n\n /// @notice Takes the given number of queued slashing operations and\n /// processes them. Receives 5% of the slashed amount.\n /// Executes `involuntaryAllocationDecrease` function on each\n /// affected application.\n function processSlashing(uint256 count) external;\n\n //\n //\n // Auxiliary functions\n //\n //\n\n /// @notice Returns the authorized stake amount of the staking provider for\n /// the application.\n function authorizedStake(address stakingProvider, address application)\n external\n view\n returns (uint96);\n\n /// @notice Returns staked amount of T, Keep and Nu for the specified\n /// staking provider.\n /// @dev All values are in T denomination\n function stakes(address stakingProvider)\n external\n view\n returns (\n uint96 tStake,\n uint96 keepInTStake,\n uint96 nuInTStake\n );\n\n /// @notice Returns start staking timestamp.\n /// @dev This value is set at most once.\n function getStartStakingTimestamp(address stakingProvider)\n external\n view\n returns (uint256);\n\n /// @notice Returns staked amount of NU for the specified staking provider.\n function stakedNu(address stakingProvider) external view returns (uint256);\n\n /// @notice Gets the stake owner, the beneficiary and the authorizer\n /// for the specified staking provider address.\n /// @return owner Stake owner address.\n /// @return beneficiary Beneficiary address.\n /// @return authorizer Authorizer address.\n function rolesOf(address stakingProvider)\n external\n view\n returns (\n address owner,\n address payable beneficiary,\n address authorizer\n );\n\n /// @notice Returns length of application array\n function getApplicationsLength() external view returns (uint256);\n\n /// @notice Returns length of slashing queue\n function getSlashingQueueLength() external view returns (uint256);\n\n /// @notice Returns minimum possible stake for T, KEEP or NU in T\n /// denomination.\n /// @dev For example, suppose the given staking provider has 10 T, 20 T\n /// worth of KEEP, and 30 T worth of NU all staked, and the maximum\n /// application authorization is 40 T, then `getMinStaked` for\n /// that staking provider returns:\n /// * 0 T if KEEP stake type specified i.e.\n /// min = 40 T max - (10 T + 30 T worth of NU) = 0 T\n /// * 10 T if NU stake type specified i.e.\n /// min = 40 T max - (10 T + 20 T worth of KEEP) = 10 T\n /// * 0 T if T stake type specified i.e.\n /// min = 40 T max - (20 T worth of KEEP + 30 T worth of NU) < 0 T\n /// In other words, the minimum stake amount for the specified\n /// stake type is the minimum amount of stake of the given type\n /// needed to satisfy the maximum application authorization given the\n /// staked amounts of the other stake types for that staking provider.\n function getMinStaked(address stakingProvider, StakeType stakeTypes)\n external\n view\n returns (uint96);\n\n /// @notice Returns available amount to authorize for the specified application\n function getAvailableToAuthorize(\n address stakingProvider,\n address application\n ) external view returns (uint96);\n}\n" + }, + "contracts/bank/Bank.sol": { + "content": "// SPDX-License-Identifier: GPL-3.0-only\n\n// ██████████████ ▐████▌ ██████████████\n// ██████████████ ▐████▌ ██████████████\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ██████████████ ▐████▌ ██████████████\n// ██████████████ ▐████▌ ██████████████\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n\npragma solidity 0.8.17;\n\nimport \"@openzeppelin/contracts/access/Ownable.sol\";\n\nimport \"./IReceiveBalanceApproval.sol\";\nimport \"../vault/IVault.sol\";\n\n/// @title Bitcoin Bank\n/// @notice Bank is a central component tracking Bitcoin balances. Balances can\n/// be transferred between balance owners, and balance owners can\n/// approve their balances to be spent by others. Balances in the Bank\n/// are updated for depositors who deposited their Bitcoin into the\n/// Bridge and only the Bridge can increase balances.\n/// @dev Bank is a governable contract and the Governance can upgrade the Bridge\n/// address.\ncontract Bank is Ownable {\n address public bridge;\n\n /// @notice The balance of the given account in the Bank. Zero by default.\n mapping(address => uint256) public balanceOf;\n\n /// @notice The remaining amount of balance a spender will be\n /// allowed to transfer on behalf of an owner using\n /// `transferBalanceFrom`. Zero by default.\n mapping(address => mapping(address => uint256)) public allowance;\n\n /// @notice Returns the current nonce for an EIP2612 permission for the\n /// provided balance owner to protect against replay attacks. Used\n /// to construct an EIP2612 signature provided to the `permit`\n /// function.\n mapping(address => uint256) public nonces;\n\n uint256 public immutable cachedChainId;\n bytes32 public immutable cachedDomainSeparator;\n\n /// @notice Returns an EIP2612 Permit message hash. Used to construct\n /// an EIP2612 signature provided to the `permit` function.\n bytes32 public constant PERMIT_TYPEHASH =\n keccak256(\n \"Permit(address owner,address spender,uint256 value,uint256 nonce,uint256 deadline)\"\n );\n\n event BalanceTransferred(\n address indexed from,\n address indexed to,\n uint256 amount\n );\n\n event BalanceApproved(\n address indexed owner,\n address indexed spender,\n uint256 amount\n );\n\n event BalanceIncreased(address indexed owner, uint256 amount);\n\n event BalanceDecreased(address indexed owner, uint256 amount);\n\n event BridgeUpdated(address newBridge);\n\n modifier onlyBridge() {\n require(msg.sender == address(bridge), \"Caller is not the bridge\");\n _;\n }\n\n constructor() {\n cachedChainId = block.chainid;\n cachedDomainSeparator = buildDomainSeparator();\n }\n\n /// @notice Allows the Governance to upgrade the Bridge address.\n /// @dev The function does not implement any governance delay and does not\n /// check the status of the Bridge. The Governance implementation needs\n /// to ensure all requirements for the upgrade are satisfied before\n /// executing this function.\n /// Requirements:\n /// - The new Bridge address must not be zero.\n /// @param _bridge The new Bridge address.\n function updateBridge(address _bridge) external onlyOwner {\n require(_bridge != address(0), \"Bridge address must not be 0x0\");\n bridge = _bridge;\n emit BridgeUpdated(_bridge);\n }\n\n /// @notice Moves the given `amount` of balance from the caller to\n /// `recipient`.\n /// @dev Requirements:\n /// - `recipient` cannot be the zero address,\n /// - the caller must have a balance of at least `amount`.\n /// @param recipient The recipient of the balance.\n /// @param amount The amount of the balance transferred.\n function transferBalance(address recipient, uint256 amount) external {\n _transferBalance(msg.sender, recipient, amount);\n }\n\n /// @notice Sets `amount` as the allowance of `spender` over the caller's\n /// balance. Does not allow updating an existing allowance to\n /// a value that is non-zero to avoid someone using both the old and\n /// the new allowance by unfortunate transaction ordering. To update\n /// an allowance to a non-zero value please set it to zero first or\n /// use `increaseBalanceAllowance` or `decreaseBalanceAllowance` for\n /// an atomic update.\n /// @dev If the `amount` is set to `type(uint256).max`,\n /// `transferBalanceFrom` will not reduce an allowance.\n /// @param spender The address that will be allowed to spend the balance.\n /// @param amount The amount the spender is allowed to spend.\n function approveBalance(address spender, uint256 amount) external {\n require(\n amount == 0 || allowance[msg.sender][spender] == 0,\n \"Non-atomic allowance change not allowed\"\n );\n _approveBalance(msg.sender, spender, amount);\n }\n\n /// @notice Sets the `amount` as an allowance of a smart contract `spender`\n /// over the caller's balance and calls the `spender` via\n /// `receiveBalanceApproval`.\n /// @dev If the `amount` is set to `type(uint256).max`, the potential\n /// `transferBalanceFrom` executed in `receiveBalanceApproval` of\n /// `spender` will not reduce an allowance. Beware that changing an\n /// allowance with this function brings the risk that `spender` may use\n /// both the old and the new allowance by unfortunate transaction\n /// ordering. Please use `increaseBalanceAllowance` and\n /// `decreaseBalanceAllowance` to eliminate the risk.\n /// @param spender The smart contract that will be allowed to spend the\n /// balance.\n /// @param amount The amount the spender contract is allowed to spend.\n /// @param extraData Extra data passed to the `spender` contract via\n /// `receiveBalanceApproval` call.\n function approveBalanceAndCall(\n address spender,\n uint256 amount,\n bytes calldata extraData\n ) external {\n _approveBalance(msg.sender, spender, amount);\n IReceiveBalanceApproval(spender).receiveBalanceApproval(\n msg.sender,\n amount,\n extraData\n );\n }\n\n /// @notice Atomically increases the caller's balance allowance granted to\n /// `spender` by the given `addedValue`.\n /// @param spender The spender address for which the allowance is increased.\n /// @param addedValue The amount by which the allowance is increased.\n function increaseBalanceAllowance(address spender, uint256 addedValue)\n external\n {\n _approveBalance(\n msg.sender,\n spender,\n allowance[msg.sender][spender] + addedValue\n );\n }\n\n /// @notice Atomically decreases the caller's balance allowance granted to\n /// `spender` by the given `subtractedValue`.\n /// @dev Requirements:\n /// - `spender` must not be the zero address,\n /// - the current allowance for `spender` must not be lower than\n /// the `subtractedValue`.\n /// @param spender The spender address for which the allowance is decreased.\n /// @param subtractedValue The amount by which the allowance is decreased.\n function decreaseBalanceAllowance(address spender, uint256 subtractedValue)\n external\n {\n uint256 currentAllowance = allowance[msg.sender][spender];\n require(\n currentAllowance >= subtractedValue,\n \"Can not decrease balance allowance below zero\"\n );\n unchecked {\n _approveBalance(\n msg.sender,\n spender,\n currentAllowance - subtractedValue\n );\n }\n }\n\n /// @notice Moves `amount` of balance from `spender` to `recipient` using the\n /// allowance mechanism. `amount` is then deducted from the caller's\n /// allowance unless the allowance was made for `type(uint256).max`.\n /// @dev Requirements:\n /// - `recipient` cannot be the zero address,\n /// - `spender` must have a balance of at least `amount`,\n /// - the caller must have an allowance for `spender`'s balance of at\n /// least `amount`.\n /// @param spender The address from which the balance is transferred.\n /// @param recipient The address to which the balance is transferred.\n /// @param amount The amount of balance that is transferred.\n function transferBalanceFrom(\n address spender,\n address recipient,\n uint256 amount\n ) external {\n uint256 currentAllowance = allowance[spender][msg.sender];\n if (currentAllowance != type(uint256).max) {\n require(\n currentAllowance >= amount,\n \"Transfer amount exceeds allowance\"\n );\n unchecked {\n _approveBalance(spender, msg.sender, currentAllowance - amount);\n }\n }\n _transferBalance(spender, recipient, amount);\n }\n\n /// @notice An EIP2612 approval made with secp256k1 signature. Users can\n /// authorize a transfer of their balance with a signature\n /// conforming to the EIP712 standard, rather than an on-chain\n /// transaction from their address. Anyone can submit this signature\n /// on the user's behalf by calling the `permit` function, paying\n /// gas fees, and possibly performing other actions in the same\n /// transaction.\n /// @dev The deadline argument can be set to `type(uint256).max to create\n /// permits that effectively never expire. If the `amount` is set\n /// to `type(uint256).max` then `transferBalanceFrom` will not\n /// reduce an allowance. Beware that changing an allowance with this\n /// function brings the risk that someone may use both the old and the\n /// new allowance by unfortunate transaction ordering. Please use\n /// `increaseBalanceAllowance` and `decreaseBalanceAllowance` to\n /// eliminate the risk.\n /// @param owner The balance owner who signed the permission.\n /// @param spender The address that will be allowed to spend the balance.\n /// @param amount The amount the spender is allowed to spend.\n /// @param deadline The UNIX time until which the permit is valid.\n /// @param v V part of the permit signature.\n /// @param r R part of the permit signature.\n /// @param s S part of the permit signature.\n function permit(\n address owner,\n address spender,\n uint256 amount,\n uint256 deadline,\n uint8 v,\n bytes32 r,\n bytes32 s\n ) external {\n /* solhint-disable-next-line not-rely-on-time */\n require(deadline >= block.timestamp, \"Permission expired\");\n\n // Validate `s` and `v` values for a malleability concern described in EIP2.\n // Only signatures with `s` value in the lower half of the secp256k1\n // curve's order and `v` value of 27 or 28 are considered valid.\n require(\n uint256(s) <=\n 0x7FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF5D576E7357A4501DDFE92F46681B20A0,\n \"Invalid signature 's' value\"\n );\n require(v == 27 || v == 28, \"Invalid signature 'v' value\");\n\n bytes32 digest = keccak256(\n abi.encodePacked(\n \"\\x19\\x01\",\n DOMAIN_SEPARATOR(),\n keccak256(\n abi.encode(\n PERMIT_TYPEHASH,\n owner,\n spender,\n amount,\n nonces[owner]++,\n deadline\n )\n )\n )\n );\n address recoveredAddress = ecrecover(digest, v, r, s);\n require(\n recoveredAddress != address(0) && recoveredAddress == owner,\n \"Invalid signature\"\n );\n _approveBalance(owner, spender, amount);\n }\n\n /// @notice Increases balances of the provided `recipients` by the provided\n /// `amounts`. Can only be called by the Bridge.\n /// @dev Requirements:\n /// - length of `recipients` and `amounts` must be the same,\n /// - none of `recipients` addresses must point to the Bank.\n /// @param recipients Balance increase recipients.\n /// @param amounts Amounts by which balances are increased.\n function increaseBalances(\n address[] calldata recipients,\n uint256[] calldata amounts\n ) external onlyBridge {\n require(\n recipients.length == amounts.length,\n \"Arrays must have the same length\"\n );\n for (uint256 i = 0; i < recipients.length; i++) {\n _increaseBalance(recipients[i], amounts[i]);\n }\n }\n\n /// @notice Increases balance of the provided `recipient` by the provided\n /// `amount`. Can only be called by the Bridge.\n /// @dev Requirements:\n /// - `recipient` address must not point to the Bank.\n /// @param recipient Balance increase recipient.\n /// @param amount Amount by which the balance is increased.\n function increaseBalance(address recipient, uint256 amount)\n external\n onlyBridge\n {\n _increaseBalance(recipient, amount);\n }\n\n /// @notice Increases the given smart contract `vault`'s balance and\n /// notifies the `vault` contract about it.\n /// Can be called only by the Bridge.\n /// @dev Requirements:\n /// - `vault` must implement `IVault` interface,\n /// - length of `recipients` and `amounts` must be the same.\n /// @param vault Address of `IVault` recipient contract.\n /// @param recipients Balance increase recipients.\n /// @param amounts Amounts by which balances are increased.\n function increaseBalanceAndCall(\n address vault,\n address[] calldata recipients,\n uint256[] calldata amounts\n ) external onlyBridge {\n require(\n recipients.length == amounts.length,\n \"Arrays must have the same length\"\n );\n uint256 totalAmount = 0;\n for (uint256 i = 0; i < amounts.length; i++) {\n totalAmount += amounts[i];\n }\n _increaseBalance(vault, totalAmount);\n IVault(vault).receiveBalanceIncrease(recipients, amounts);\n }\n\n /// @notice Decreases caller's balance by the provided `amount`. There is no\n /// way to restore the balance so do not call this function unless\n /// you really know what you are doing!\n /// @dev Requirements:\n /// - The caller must have a balance of at least `amount`.\n /// @param amount The amount by which the balance is decreased.\n function decreaseBalance(uint256 amount) external {\n balanceOf[msg.sender] -= amount;\n emit BalanceDecreased(msg.sender, amount);\n }\n\n /// @notice Returns hash of EIP712 Domain struct with `TBTC Bank` as\n /// a signing domain and Bank contract as a verifying contract.\n /// Used to construct an EIP2612 signature provided to the `permit`\n /// function.\n /* solhint-disable-next-line func-name-mixedcase */\n function DOMAIN_SEPARATOR() public view returns (bytes32) {\n // As explained in EIP-2612, if the DOMAIN_SEPARATOR contains the\n // chainId and is defined at contract deployment instead of\n // reconstructed for every signature, there is a risk of possible replay\n // attacks between chains in the event of a future chain split.\n // To address this issue, we check the cached chain ID against the\n // current one and in case they are different, we build domain separator\n // from scratch.\n if (block.chainid == cachedChainId) {\n return cachedDomainSeparator;\n } else {\n return buildDomainSeparator();\n }\n }\n\n function _increaseBalance(address recipient, uint256 amount) internal {\n require(\n recipient != address(this),\n \"Can not increase balance for Bank\"\n );\n balanceOf[recipient] += amount;\n emit BalanceIncreased(recipient, amount);\n }\n\n function _transferBalance(\n address spender,\n address recipient,\n uint256 amount\n ) private {\n require(\n recipient != address(0),\n \"Can not transfer to the zero address\"\n );\n require(\n recipient != address(this),\n \"Can not transfer to the Bank address\"\n );\n\n uint256 spenderBalance = balanceOf[spender];\n require(spenderBalance >= amount, \"Transfer amount exceeds balance\");\n unchecked {\n balanceOf[spender] = spenderBalance - amount;\n }\n balanceOf[recipient] += amount;\n emit BalanceTransferred(spender, recipient, amount);\n }\n\n function _approveBalance(\n address owner,\n address spender,\n uint256 amount\n ) private {\n require(spender != address(0), \"Can not approve to the zero address\");\n allowance[owner][spender] = amount;\n emit BalanceApproved(owner, spender, amount);\n }\n\n function buildDomainSeparator() private view returns (bytes32) {\n return\n keccak256(\n abi.encode(\n keccak256(\n \"EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)\"\n ),\n keccak256(bytes(\"TBTC Bank\")),\n keccak256(bytes(\"1\")),\n block.chainid,\n address(this)\n )\n );\n }\n}\n" + }, + "contracts/bank/IReceiveBalanceApproval.sol": { + "content": "// SPDX-License-Identifier: GPL-3.0-only\n\n// ██████████████ ▐████▌ ██████████████\n// ██████████████ ▐████▌ ██████████████\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ██████████████ ▐████▌ ██████████████\n// ██████████████ ▐████▌ ██████████████\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n\npragma solidity 0.8.17;\n\n/// @title IReceiveBalanceApproval\n/// @notice `IReceiveBalanceApproval` is an interface for a smart contract\n/// consuming Bank balances approved to them in the same transaction by\n/// other contracts or externally owned accounts (EOA).\ninterface IReceiveBalanceApproval {\n /// @notice Called by the Bank in `approveBalanceAndCall` function after\n /// the balance `owner` approved `amount` of their balance in the\n /// Bank for the contract. This way, the depositor can approve\n /// balance and call the contract to use the approved balance in\n /// a single transaction.\n /// @param owner Address of the Bank balance owner who approved their\n /// balance to be used by the contract.\n /// @param amount The amount of the Bank balance approved by the owner\n /// to be used by the contract.\n /// @param extraData The `extraData` passed to `Bank.approveBalanceAndCall`.\n /// @dev The implementation must ensure this function can only be called\n /// by the Bank. The Bank does _not_ guarantee that the `amount`\n /// approved by the `owner` currently exists on their balance. That is,\n /// the `owner` could approve more balance than they currently have.\n /// This works the same as `Bank.approve` function. The contract must\n /// ensure the actual balance is checked before performing any action\n /// based on it.\n function receiveBalanceApproval(\n address owner,\n uint256 amount,\n bytes calldata extraData\n ) external;\n}\n" + }, + "contracts/bridge/BitcoinTx.sol": { + "content": "// SPDX-License-Identifier: GPL-3.0-only\n\n// ██████████████ ▐████▌ ██████████████\n// ██████████████ ▐████▌ ██████████████\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ██████████████ ▐████▌ ██████████████\n// ██████████████ ▐████▌ ██████████████\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n\npragma solidity 0.8.17;\n\nimport {BTCUtils} from \"@keep-network/bitcoin-spv-sol/contracts/BTCUtils.sol\";\nimport {BytesLib} from \"@keep-network/bitcoin-spv-sol/contracts/BytesLib.sol\";\nimport {ValidateSPV} from \"@keep-network/bitcoin-spv-sol/contracts/ValidateSPV.sol\";\n\nimport \"./BridgeState.sol\";\n\n/// @title Bitcoin transaction\n/// @notice Allows to reference Bitcoin raw transaction in Solidity.\n/// @dev See https://developer.bitcoin.org/reference/transactions.html#raw-transaction-format\n///\n/// Raw Bitcoin transaction data:\n///\n/// | Bytes | Name | BTC type | Description |\n/// |--------|--------------|------------------------|---------------------------|\n/// | 4 | version | int32_t (LE) | TX version number |\n/// | varies | tx_in_count | compactSize uint (LE) | Number of TX inputs |\n/// | varies | tx_in | txIn[] | TX inputs |\n/// | varies | tx_out_count | compactSize uint (LE) | Number of TX outputs |\n/// | varies | tx_out | txOut[] | TX outputs |\n/// | 4 | lock_time | uint32_t (LE) | Unix time or block number |\n///\n//\n/// Non-coinbase transaction input (txIn):\n///\n/// | Bytes | Name | BTC type | Description |\n/// |--------|------------------|------------------------|---------------------------------------------|\n/// | 36 | previous_output | outpoint | The previous outpoint being spent |\n/// | varies | script_bytes | compactSize uint (LE) | The number of bytes in the signature script |\n/// | varies | signature_script | char[] | The signature script, empty for P2WSH |\n/// | 4 | sequence | uint32_t (LE) | Sequence number |\n///\n///\n/// The reference to transaction being spent (outpoint):\n///\n/// | Bytes | Name | BTC type | Description |\n/// |-------|-------|---------------|------------------------------------------|\n/// | 32 | hash | char[32] | Hash of the transaction to spend |\n/// | 4 | index | uint32_t (LE) | Index of the specific output from the TX |\n///\n///\n/// Transaction output (txOut):\n///\n/// | Bytes | Name | BTC type | Description |\n/// |--------|-----------------|-----------------------|--------------------------------------|\n/// | 8 | value | int64_t (LE) | Number of satoshis to spend |\n/// | 1+ | pk_script_bytes | compactSize uint (LE) | Number of bytes in the pubkey script |\n/// | varies | pk_script | char[] | Pubkey script |\n///\n/// compactSize uint format:\n///\n/// | Value | Bytes | Format |\n/// |-----------------------------------------|-------|----------------------------------------------|\n/// | >= 0 && <= 252 | 1 | uint8_t |\n/// | >= 253 && <= 0xffff | 3 | 0xfd followed by the number as uint16_t (LE) |\n/// | >= 0x10000 && <= 0xffffffff | 5 | 0xfe followed by the number as uint32_t (LE) |\n/// | >= 0x100000000 && <= 0xffffffffffffffff | 9 | 0xff followed by the number as uint64_t (LE) |\n///\n/// (*) compactSize uint is often references as VarInt)\n///\n/// Coinbase transaction input (txIn):\n///\n/// | Bytes | Name | BTC type | Description |\n/// |--------|------------------|------------------------|---------------------------------------------|\n/// | 32 | hash | char[32] | A 32-byte 0x0 null (no previous_outpoint) |\n/// | 4 | index | uint32_t (LE) | 0xffffffff (no previous_outpoint) |\n/// | varies | script_bytes | compactSize uint (LE) | The number of bytes in the coinbase script |\n/// | varies | height | char[] | The block height of this block (BIP34) (*) |\n/// | varies | coinbase_script | none | Arbitrary data, max 100 bytes |\n/// | 4 | sequence | uint32_t (LE) | Sequence number\n///\n/// (*) Uses script language: starts with a data-pushing opcode that indicates how many bytes to push to\n/// the stack followed by the block height as a little-endian unsigned integer. This script must be as\n/// short as possible, otherwise it may be rejected. The data-pushing opcode will be 0x03 and the total\n/// size four bytes until block 16,777,216 about 300 years from now.\nlibrary BitcoinTx {\n using BTCUtils for bytes;\n using BTCUtils for uint256;\n using BytesLib for bytes;\n using ValidateSPV for bytes;\n using ValidateSPV for bytes32;\n\n /// @notice Represents Bitcoin transaction data.\n struct Info {\n /// @notice Bitcoin transaction version.\n /// @dev `version` from raw Bitcoin transaction data.\n /// Encoded as 4-bytes signed integer, little endian.\n bytes4 version;\n /// @notice All Bitcoin transaction inputs, prepended by the number of\n /// transaction inputs.\n /// @dev `tx_in_count | tx_in` from raw Bitcoin transaction data.\n ///\n /// The number of transaction inputs encoded as compactSize\n /// unsigned integer, little-endian.\n ///\n /// Note that some popular block explorers reverse the order of\n /// bytes from `outpoint`'s `hash` and display it as big-endian.\n /// Solidity code of Bridge expects hashes in little-endian, just\n /// like they are represented in a raw Bitcoin transaction.\n bytes inputVector;\n /// @notice All Bitcoin transaction outputs prepended by the number of\n /// transaction outputs.\n /// @dev `tx_out_count | tx_out` from raw Bitcoin transaction data.\n ///\n /// The number of transaction outputs encoded as a compactSize\n /// unsigned integer, little-endian.\n bytes outputVector;\n /// @notice Bitcoin transaction locktime.\n ///\n /// @dev `lock_time` from raw Bitcoin transaction data.\n /// Encoded as 4-bytes unsigned integer, little endian.\n bytes4 locktime;\n // This struct doesn't contain `__gap` property as the structure is not\n // stored, it is used as a function's calldata argument.\n }\n\n /// @notice Represents data needed to perform a Bitcoin SPV proof.\n struct Proof {\n /// @notice The merkle proof of transaction inclusion in a block.\n bytes merkleProof;\n /// @notice Transaction index in the block (0-indexed).\n uint256 txIndexInBlock;\n /// @notice Single byte-string of 80-byte bitcoin headers,\n /// lowest height first.\n bytes bitcoinHeaders;\n /// @notice The sha256 preimage of the coinbase tx hash\n /// i.e. the sha256 hash of the coinbase transaction.\n bytes32 coinbasePreimage;\n /// @notice The merkle proof of the coinbase transaction.\n bytes coinbaseProof;\n // This struct doesn't contain `__gap` property as the structure is not\n // stored, it is used as a function's calldata argument.\n }\n\n /// @notice Represents info about an unspent transaction output.\n struct UTXO {\n /// @notice Hash of the transaction the output belongs to.\n /// @dev Byte order corresponds to the Bitcoin internal byte order.\n bytes32 txHash;\n /// @notice Index of the transaction output (0-indexed).\n uint32 txOutputIndex;\n /// @notice Value of the transaction output.\n uint64 txOutputValue;\n // This struct doesn't contain `__gap` property as the structure is not\n // stored, it is used as a function's calldata argument.\n }\n\n /// @notice Represents Bitcoin signature in the R/S/V format.\n struct RSVSignature {\n /// @notice Signature r value.\n bytes32 r;\n /// @notice Signature s value.\n bytes32 s;\n /// @notice Signature recovery value.\n uint8 v;\n // This struct doesn't contain `__gap` property as the structure is not\n // stored, it is used as a function's calldata argument.\n }\n\n /// @notice Validates the SPV proof of the Bitcoin transaction.\n /// Reverts in case the validation or proof verification fail.\n /// @param txInfo Bitcoin transaction data.\n /// @param proof Bitcoin proof data.\n /// @return txHash Proven 32-byte transaction hash.\n function validateProof(\n BridgeState.Storage storage self,\n Info calldata txInfo,\n Proof calldata proof\n ) internal view returns (bytes32 txHash) {\n require(\n txInfo.inputVector.validateVin(),\n \"Invalid input vector provided\"\n );\n require(\n txInfo.outputVector.validateVout(),\n \"Invalid output vector provided\"\n );\n require(\n proof.merkleProof.length == proof.coinbaseProof.length,\n \"Tx not on same level of merkle tree as coinbase\"\n );\n\n txHash = abi\n .encodePacked(\n txInfo.version,\n txInfo.inputVector,\n txInfo.outputVector,\n txInfo.locktime\n )\n .hash256View();\n\n bytes32 root = proof.bitcoinHeaders.extractMerkleRootLE();\n\n require(\n txHash.prove(root, proof.merkleProof, proof.txIndexInBlock),\n \"Tx merkle proof is not valid for provided header and tx hash\"\n );\n\n bytes32 coinbaseHash = sha256(abi.encodePacked(proof.coinbasePreimage));\n\n require(\n coinbaseHash.prove(root, proof.coinbaseProof, 0),\n \"Coinbase merkle proof is not valid for provided header and hash\"\n );\n\n evaluateProofDifficulty(self, proof.bitcoinHeaders);\n\n return txHash;\n }\n\n /// @notice Evaluates the given Bitcoin proof difficulty against the actual\n /// Bitcoin chain difficulty provided by the relay oracle.\n /// Reverts in case the evaluation fails.\n /// @param bitcoinHeaders Bitcoin headers chain being part of the SPV\n /// proof. Used to extract the observed proof difficulty.\n function evaluateProofDifficulty(\n BridgeState.Storage storage self,\n bytes memory bitcoinHeaders\n ) internal view {\n IRelay relay = self.relay;\n uint256 currentEpochDifficulty = relay.getCurrentEpochDifficulty();\n uint256 previousEpochDifficulty = relay.getPrevEpochDifficulty();\n\n uint256 requestedDiff = 0;\n uint256 firstHeaderDiff = bitcoinHeaders\n .extractTarget()\n .calculateDifficulty();\n\n if (firstHeaderDiff == currentEpochDifficulty) {\n requestedDiff = currentEpochDifficulty;\n } else if (firstHeaderDiff == previousEpochDifficulty) {\n requestedDiff = previousEpochDifficulty;\n } else {\n revert(\"Not at current or previous difficulty\");\n }\n\n uint256 observedDiff = bitcoinHeaders.validateHeaderChain();\n\n require(\n observedDiff != ValidateSPV.getErrBadLength(),\n \"Invalid length of the headers chain\"\n );\n require(\n observedDiff != ValidateSPV.getErrInvalidChain(),\n \"Invalid headers chain\"\n );\n require(\n observedDiff != ValidateSPV.getErrLowWork(),\n \"Insufficient work in a header\"\n );\n\n require(\n observedDiff >= requestedDiff * self.txProofDifficultyFactor,\n \"Insufficient accumulated difficulty in header chain\"\n );\n }\n\n /// @notice Extracts public key hash from the provided P2PKH or P2WPKH output.\n /// Reverts if the validation fails.\n /// @param output The transaction output.\n /// @return pubKeyHash 20-byte public key hash the output locks funds on.\n /// @dev Requirements:\n /// - The output must be of P2PKH or P2WPKH type and lock the funds\n /// on a 20-byte public key hash.\n function extractPubKeyHash(BridgeState.Storage storage, bytes memory output)\n internal\n pure\n returns (bytes20 pubKeyHash)\n {\n bytes memory pubKeyHashBytes = output.extractHash();\n\n require(\n pubKeyHashBytes.length == 20,\n \"Output's public key hash must have 20 bytes\"\n );\n\n pubKeyHash = pubKeyHashBytes.slice20(0);\n\n // The output consists of an 8-byte value and a variable length script.\n // To extract just the script, we ignore the first 8 bytes.\n uint256 scriptLen = output.length - 8;\n\n // The P2PKH script is 26 bytes long.\n // The P2WPKH script is 23 bytes long.\n // A valid script must have one of these lengths,\n // and we can identify the expected script type by the length.\n require(\n scriptLen == 26 || scriptLen == 23,\n \"Output must be P2PKH or P2WPKH\"\n );\n\n if (scriptLen == 26) {\n // Compare to the expected P2PKH script.\n bytes26 script = bytes26(output.slice32(8));\n\n require(\n script == makeP2PKHScript(pubKeyHash),\n \"Invalid P2PKH script\"\n );\n }\n\n if (scriptLen == 23) {\n // Compare to the expected P2WPKH script.\n bytes23 script = bytes23(output.slice32(8));\n\n require(\n script == makeP2WPKHScript(pubKeyHash),\n \"Invalid P2WPKH script\"\n );\n }\n\n return pubKeyHash;\n }\n\n /// @notice Build the P2PKH script from the given public key hash.\n /// @param pubKeyHash The 20-byte public key hash.\n /// @return The P2PKH script.\n /// @dev The P2PKH script has the following byte format:\n /// <0x1976a914> <20-byte PKH> <0x88ac>. According to\n /// https://en.bitcoin.it/wiki/Script#Opcodes this translates to:\n /// - 0x19: Byte length of the entire script\n /// - 0x76: OP_DUP\n /// - 0xa9: OP_HASH160\n /// - 0x14: Byte length of the public key hash\n /// - 0x88: OP_EQUALVERIFY\n /// - 0xac: OP_CHECKSIG\n /// which matches the P2PKH structure as per:\n /// https://en.bitcoin.it/wiki/Transaction#Pay-to-PubkeyHash\n function makeP2PKHScript(bytes20 pubKeyHash)\n internal\n pure\n returns (bytes26)\n {\n bytes26 P2PKHScriptMask = hex\"1976a914000000000000000000000000000000000000000088ac\";\n\n return ((bytes26(pubKeyHash) >> 32) | P2PKHScriptMask);\n }\n\n /// @notice Build the P2WPKH script from the given public key hash.\n /// @param pubKeyHash The 20-byte public key hash.\n /// @return The P2WPKH script.\n /// @dev The P2WPKH script has the following format:\n /// <0x160014> <20-byte PKH>. According to\n /// https://en.bitcoin.it/wiki/Script#Opcodes this translates to:\n /// - 0x16: Byte length of the entire script\n /// - 0x00: OP_0\n /// - 0x14: Byte length of the public key hash\n /// which matches the P2WPKH structure as per:\n /// https://github.com/bitcoin/bips/blob/master/bip-0141.mediawiki#P2WPKH\n function makeP2WPKHScript(bytes20 pubKeyHash)\n internal\n pure\n returns (bytes23)\n {\n bytes23 P2WPKHScriptMask = hex\"1600140000000000000000000000000000000000000000\";\n\n return ((bytes23(pubKeyHash) >> 24) | P2WPKHScriptMask);\n }\n}\n" + }, + "contracts/bridge/Bridge.sol": { + "content": "// SPDX-License-Identifier: GPL-3.0-only\n\n// ██████████████ ▐████▌ ██████████████\n// ██████████████ ▐████▌ ██████████████\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ██████████████ ▐████▌ ██████████████\n// ██████████████ ▐████▌ ██████████████\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n\npragma solidity 0.8.17;\n\nimport \"@keep-network/random-beacon/contracts/Governable.sol\";\nimport \"@keep-network/random-beacon/contracts/ReimbursementPool.sol\";\nimport {IWalletOwner as EcdsaWalletOwner} from \"@keep-network/ecdsa/contracts/api/IWalletOwner.sol\";\n\nimport \"@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol\";\nimport \"@openzeppelin/contracts-upgradeable/utils/math/SafeCastUpgradeable.sol\";\n\nimport \"./IRelay.sol\";\nimport \"./BridgeState.sol\";\nimport \"./Deposit.sol\";\nimport \"./DepositSweep.sol\";\nimport \"./Redemption.sol\";\nimport \"./BitcoinTx.sol\";\nimport \"./EcdsaLib.sol\";\nimport \"./Wallets.sol\";\nimport \"./Fraud.sol\";\nimport \"./MovingFunds.sol\";\n\nimport \"../bank/IReceiveBalanceApproval.sol\";\nimport \"../bank/Bank.sol\";\n\n/// @title Bitcoin Bridge\n/// @notice Bridge manages BTC deposit and redemption flow and is increasing and\n/// decreasing balances in the Bank as a result of BTC deposit and\n/// redemption operations performed by depositors and redeemers.\n///\n/// Depositors send BTC funds to the most recently created off-chain\n/// ECDSA wallet of the bridge using pay-to-script-hash (P2SH) or\n/// pay-to-witness-script-hash (P2WSH) containing hashed information\n/// about the depositor’s Ethereum address. Then, the depositor reveals\n/// their Ethereum address along with their deposit blinding factor,\n/// refund public key hash and refund locktime to the Bridge on Ethereum\n/// chain. The off-chain ECDSA wallet listens for these sorts of\n/// messages and when it gets one, it checks the Bitcoin network to make\n/// sure the deposit lines up. If it does, the off-chain ECDSA wallet\n/// may decide to pick the deposit transaction for sweeping, and when\n/// the sweep operation is confirmed on the Bitcoin network, the ECDSA\n/// wallet informs the Bridge about the sweep increasing appropriate\n/// balances in the Bank.\n/// @dev Bridge is an upgradeable component of the Bank. The order of\n/// functionalities in this contract is: deposit, sweep, redemption,\n/// moving funds, wallet lifecycle, frauds, parameters.\ncontract Bridge is\n Governable,\n EcdsaWalletOwner,\n Initializable,\n IReceiveBalanceApproval\n{\n using BridgeState for BridgeState.Storage;\n using Deposit for BridgeState.Storage;\n using DepositSweep for BridgeState.Storage;\n using Redemption for BridgeState.Storage;\n using MovingFunds for BridgeState.Storage;\n using Wallets for BridgeState.Storage;\n using Fraud for BridgeState.Storage;\n\n BridgeState.Storage internal self;\n\n event DepositRevealed(\n bytes32 fundingTxHash,\n uint32 fundingOutputIndex,\n address indexed depositor,\n uint64 amount,\n bytes8 blindingFactor,\n bytes20 indexed walletPubKeyHash,\n bytes20 refundPubKeyHash,\n bytes4 refundLocktime,\n address vault\n );\n\n event DepositsSwept(bytes20 walletPubKeyHash, bytes32 sweepTxHash);\n\n event RedemptionRequested(\n bytes20 indexed walletPubKeyHash,\n bytes redeemerOutputScript,\n address indexed redeemer,\n uint64 requestedAmount,\n uint64 treasuryFee,\n uint64 txMaxFee\n );\n\n event RedemptionsCompleted(\n bytes20 indexed walletPubKeyHash,\n bytes32 redemptionTxHash\n );\n\n event RedemptionTimedOut(\n bytes20 indexed walletPubKeyHash,\n bytes redeemerOutputScript\n );\n\n event WalletMovingFunds(\n bytes32 indexed ecdsaWalletID,\n bytes20 indexed walletPubKeyHash\n );\n\n event MovingFundsCommitmentSubmitted(\n bytes20 indexed walletPubKeyHash,\n bytes20[] targetWallets,\n address submitter\n );\n\n event MovingFundsTimeoutReset(bytes20 indexed walletPubKeyHash);\n\n event MovingFundsCompleted(\n bytes20 indexed walletPubKeyHash,\n bytes32 movingFundsTxHash\n );\n\n event MovingFundsTimedOut(bytes20 indexed walletPubKeyHash);\n\n event MovingFundsBelowDustReported(bytes20 indexed walletPubKeyHash);\n\n event MovedFundsSwept(\n bytes20 indexed walletPubKeyHash,\n bytes32 sweepTxHash\n );\n\n event MovedFundsSweepTimedOut(\n bytes20 indexed walletPubKeyHash,\n bytes32 movingFundsTxHash,\n uint32 movingFundsTxOutputIndex\n );\n\n event NewWalletRequested();\n\n event NewWalletRegistered(\n bytes32 indexed ecdsaWalletID,\n bytes20 indexed walletPubKeyHash\n );\n\n event WalletClosing(\n bytes32 indexed ecdsaWalletID,\n bytes20 indexed walletPubKeyHash\n );\n\n event WalletClosed(\n bytes32 indexed ecdsaWalletID,\n bytes20 indexed walletPubKeyHash\n );\n\n event WalletTerminated(\n bytes32 indexed ecdsaWalletID,\n bytes20 indexed walletPubKeyHash\n );\n\n event FraudChallengeSubmitted(\n bytes20 indexed walletPubKeyHash,\n bytes32 sighash,\n uint8 v,\n bytes32 r,\n bytes32 s\n );\n\n event FraudChallengeDefeated(\n bytes20 indexed walletPubKeyHash,\n bytes32 sighash\n );\n\n event FraudChallengeDefeatTimedOut(\n bytes20 indexed walletPubKeyHash,\n bytes32 sighash\n );\n\n event VaultStatusUpdated(address indexed vault, bool isTrusted);\n\n event SpvMaintainerStatusUpdated(\n address indexed spvMaintainer,\n bool isTrusted\n );\n\n event DepositParametersUpdated(\n uint64 depositDustThreshold,\n uint64 depositTreasuryFeeDivisor,\n uint64 depositTxMaxFee,\n uint32 depositRevealAheadPeriod\n );\n\n event RedemptionParametersUpdated(\n uint64 redemptionDustThreshold,\n uint64 redemptionTreasuryFeeDivisor,\n uint64 redemptionTxMaxFee,\n uint64 redemptionTxMaxTotalFee,\n uint32 redemptionTimeout,\n uint96 redemptionTimeoutSlashingAmount,\n uint32 redemptionTimeoutNotifierRewardMultiplier\n );\n\n event MovingFundsParametersUpdated(\n uint64 movingFundsTxMaxTotalFee,\n uint64 movingFundsDustThreshold,\n uint32 movingFundsTimeoutResetDelay,\n uint32 movingFundsTimeout,\n uint96 movingFundsTimeoutSlashingAmount,\n uint32 movingFundsTimeoutNotifierRewardMultiplier,\n uint16 movingFundsCommitmentGasOffset,\n uint64 movedFundsSweepTxMaxTotalFee,\n uint32 movedFundsSweepTimeout,\n uint96 movedFundsSweepTimeoutSlashingAmount,\n uint32 movedFundsSweepTimeoutNotifierRewardMultiplier\n );\n\n event WalletParametersUpdated(\n uint32 walletCreationPeriod,\n uint64 walletCreationMinBtcBalance,\n uint64 walletCreationMaxBtcBalance,\n uint64 walletClosureMinBtcBalance,\n uint32 walletMaxAge,\n uint64 walletMaxBtcTransfer,\n uint32 walletClosingPeriod\n );\n\n event FraudParametersUpdated(\n uint96 fraudChallengeDepositAmount,\n uint32 fraudChallengeDefeatTimeout,\n uint96 fraudSlashingAmount,\n uint32 fraudNotifierRewardMultiplier\n );\n\n event TreasuryUpdated(address treasury);\n\n modifier onlySpvMaintainer() {\n require(\n self.isSpvMaintainer[msg.sender],\n \"Caller is not SPV maintainer\"\n );\n _;\n }\n\n /// @custom:oz-upgrades-unsafe-allow constructor\n constructor() {\n _disableInitializers();\n }\n\n /// @dev Initializes upgradable contract on deployment.\n /// @param _bank Address of the Bank the Bridge belongs to.\n /// @param _relay Address of the Bitcoin relay providing the current Bitcoin\n /// network difficulty.\n /// @param _treasury Address where the deposit and redemption treasury fees\n /// will be sent to.\n /// @param _ecdsaWalletRegistry Address of the ECDSA Wallet Registry contract.\n /// @param _reimbursementPool Address of the Reimbursement Pool contract.\n /// @param _txProofDifficultyFactor The number of confirmations on the Bitcoin\n /// chain required to successfully evaluate an SPV proof.\n function initialize(\n address _bank,\n address _relay,\n address _treasury,\n address _ecdsaWalletRegistry,\n address payable _reimbursementPool,\n uint96 _txProofDifficultyFactor\n ) external initializer {\n require(_bank != address(0), \"Bank address cannot be zero\");\n self.bank = Bank(_bank);\n\n require(_relay != address(0), \"Relay address cannot be zero\");\n self.relay = IRelay(_relay);\n\n require(\n _ecdsaWalletRegistry != address(0),\n \"ECDSA Wallet Registry address cannot be zero\"\n );\n self.ecdsaWalletRegistry = EcdsaWalletRegistry(_ecdsaWalletRegistry);\n\n require(\n _reimbursementPool != address(0),\n \"Reimbursement Pool address cannot be zero\"\n );\n self.reimbursementPool = ReimbursementPool(_reimbursementPool);\n\n require(_treasury != address(0), \"Treasury address cannot be zero\");\n self.treasury = _treasury;\n\n self.txProofDifficultyFactor = _txProofDifficultyFactor;\n\n //\n // All parameters set in the constructor are initial ones, used at the\n // moment contracts were deployed for the first time. Parameters are\n // governable and values assigned in the constructor do not need to\n // reflect the current ones. Keep in mind the initial parameters are\n // pretty forgiving and valid only for the early stage of the network.\n //\n\n self.depositDustThreshold = 1000000; // 1000000 satoshi = 0.01 BTC\n self.depositTxMaxFee = 100000; // 100000 satoshi = 0.001 BTC\n self.depositRevealAheadPeriod = 15 days;\n self.depositTreasuryFeeDivisor = 2000; // 1/2000 == 5bps == 0.05% == 0.0005\n self.redemptionDustThreshold = 1000000; // 1000000 satoshi = 0.01 BTC\n self.redemptionTreasuryFeeDivisor = 2000; // 1/2000 == 5bps == 0.05% == 0.0005\n self.redemptionTxMaxFee = 100000; // 100000 satoshi = 0.001 BTC\n self.redemptionTxMaxTotalFee = 1000000; // 1000000 satoshi = 0.01 BTC\n self.redemptionTimeout = 5 days;\n self.redemptionTimeoutSlashingAmount = 100 * 1e18; // 100 T\n self.redemptionTimeoutNotifierRewardMultiplier = 100; // 100%\n self.movingFundsTxMaxTotalFee = 100000; // 100000 satoshi = 0.001 BTC\n self.movingFundsDustThreshold = 200000; // 200000 satoshi = 0.002 BTC\n self.movingFundsTimeoutResetDelay = 6 days;\n self.movingFundsTimeout = 7 days;\n self.movingFundsTimeoutSlashingAmount = 100 * 1e18; // 100 T\n self.movingFundsTimeoutNotifierRewardMultiplier = 100; //100%\n self.movingFundsCommitmentGasOffset = 15000;\n self.movedFundsSweepTxMaxTotalFee = 100000; // 100000 satoshi = 0.001 BTC\n self.movedFundsSweepTimeout = 7 days;\n self.movedFundsSweepTimeoutSlashingAmount = 100 * 1e18; // 100 T\n self.movedFundsSweepTimeoutNotifierRewardMultiplier = 100; //100%\n self.fraudChallengeDepositAmount = 5 ether;\n self.fraudChallengeDefeatTimeout = 7 days;\n self.fraudSlashingAmount = 100 * 1e18; // 100 T\n self.fraudNotifierRewardMultiplier = 100; // 100%\n self.walletCreationPeriod = 1 weeks;\n self.walletCreationMinBtcBalance = 1e8; // 1 BTC\n self.walletCreationMaxBtcBalance = 100e8; // 100 BTC\n self.walletClosureMinBtcBalance = 5 * 1e7; // 0.5 BTC\n self.walletMaxAge = 26 weeks; // ~6 months\n self.walletMaxBtcTransfer = 10e8; // 10 BTC\n self.walletClosingPeriod = 40 days;\n\n _transferGovernance(msg.sender);\n }\n\n /// @notice Used by the depositor to reveal information about their P2(W)SH\n /// Bitcoin deposit to the Bridge on Ethereum chain. The off-chain\n /// wallet listens for revealed deposit events and may decide to\n /// include the revealed deposit in the next executed sweep.\n /// Information about the Bitcoin deposit can be revealed before or\n /// after the Bitcoin transaction with P2(W)SH deposit is mined on\n /// the Bitcoin chain. Worth noting, the gas cost of this function\n /// scales with the number of P2(W)SH transaction inputs and\n /// outputs. The deposit may be routed to one of the trusted vaults.\n /// When a deposit is routed to a vault, vault gets notified when\n /// the deposit gets swept and it may execute the appropriate action.\n /// @param fundingTx Bitcoin funding transaction data, see `BitcoinTx.Info`.\n /// @param reveal Deposit reveal data, see `RevealInfo struct.\n /// @dev Requirements:\n /// - This function must be called by the same Ethereum address as the\n /// one used in the P2(W)SH BTC deposit transaction as a depositor,\n /// - `reveal.walletPubKeyHash` must identify a `Live` wallet,\n /// - `reveal.vault` must be 0x0 or point to a trusted vault,\n /// - `reveal.fundingOutputIndex` must point to the actual P2(W)SH\n /// output of the BTC deposit transaction,\n /// - `reveal.blindingFactor` must be the blinding factor used in the\n /// P2(W)SH BTC deposit transaction,\n /// - `reveal.walletPubKeyHash` must be the wallet pub key hash used in\n /// the P2(W)SH BTC deposit transaction,\n /// - `reveal.refundPubKeyHash` must be the refund pub key hash used in\n /// the P2(W)SH BTC deposit transaction,\n /// - `reveal.refundLocktime` must be the refund locktime used in the\n /// P2(W)SH BTC deposit transaction,\n /// - BTC deposit for the given `fundingTxHash`, `fundingOutputIndex`\n /// can be revealed only one time.\n ///\n /// If any of these requirements is not met, the wallet _must_ refuse\n /// to sweep the deposit and the depositor has to wait until the\n /// deposit script unlocks to receive their BTC back.\n function revealDeposit(\n BitcoinTx.Info calldata fundingTx,\n Deposit.DepositRevealInfo calldata reveal\n ) external {\n self.revealDeposit(fundingTx, reveal);\n }\n\n /// @notice Used by the wallet to prove the BTC deposit sweep transaction\n /// and to update Bank balances accordingly. Sweep is only accepted\n /// if it satisfies SPV proof.\n ///\n /// The function is performing Bank balance updates by first\n /// computing the Bitcoin fee for the sweep transaction. The fee is\n /// divided evenly between all swept deposits. Each depositor\n /// receives a balance in the bank equal to the amount inferred\n /// during the reveal transaction, minus their fee share.\n ///\n /// It is possible to prove the given sweep only one time.\n /// @param sweepTx Bitcoin sweep transaction data.\n /// @param sweepProof Bitcoin sweep proof data.\n /// @param mainUtxo Data of the wallet's main UTXO, as currently known on\n /// the Ethereum chain. If no main UTXO exists for the given wallet,\n /// this parameter is ignored.\n /// @param vault Optional address of the vault where all swept deposits\n /// should be routed to. All deposits swept as part of the transaction\n /// must have their `vault` parameters set to the same address.\n /// If this parameter is set to an address of a trusted vault, swept\n /// deposits are routed to that vault.\n /// If this parameter is set to the zero address or to an address\n /// of a non-trusted vault, swept deposits are not routed to a\n /// vault but depositors' balances are increased in the Bank\n /// individually.\n /// @dev Requirements:\n /// - `sweepTx` components must match the expected structure. See\n /// `BitcoinTx.Info` docs for reference. Their values must exactly\n /// correspond to appropriate Bitcoin transaction fields to produce\n /// a provable transaction hash,\n /// - The `sweepTx` should represent a Bitcoin transaction with 1..n\n /// inputs. If the wallet has no main UTXO, all n inputs should\n /// correspond to P2(W)SH revealed deposits UTXOs. If the wallet has\n /// an existing main UTXO, one of the n inputs must point to that\n /// main UTXO and remaining n-1 inputs should correspond to P2(W)SH\n /// revealed deposits UTXOs. That transaction must have only\n /// one P2(W)PKH output locking funds on the 20-byte wallet public\n /// key hash,\n /// - All revealed deposits that are swept by `sweepTx` must have\n /// their `vault` parameters set to the same address as the address\n /// passed in the `vault` function parameter,\n /// - `sweepProof` components must match the expected structure. See\n /// `BitcoinTx.Proof` docs for reference. The `bitcoinHeaders`\n /// field must contain a valid number of block headers, not less\n /// than the `txProofDifficultyFactor` contract constant,\n /// - `mainUtxo` components must point to the recent main UTXO\n /// of the given wallet, as currently known on the Ethereum chain.\n /// If there is no main UTXO, this parameter is ignored.\n function submitDepositSweepProof(\n BitcoinTx.Info calldata sweepTx,\n BitcoinTx.Proof calldata sweepProof,\n BitcoinTx.UTXO calldata mainUtxo,\n address vault\n ) external onlySpvMaintainer {\n self.submitDepositSweepProof(sweepTx, sweepProof, mainUtxo, vault);\n }\n\n /// @notice Requests redemption of the given amount from the specified\n /// wallet to the redeemer Bitcoin output script. Handles the\n /// simplest case in which the redeemer's balance is decreased in\n /// the Bank.\n /// @param walletPubKeyHash The 20-byte wallet public key hash (computed\n /// using Bitcoin HASH160 over the compressed ECDSA public key).\n /// @param mainUtxo Data of the wallet's main UTXO, as currently known on\n /// the Ethereum chain.\n /// @param redeemerOutputScript The redeemer's length-prefixed output\n /// script (P2PKH, P2WPKH, P2SH or P2WSH) that will be used to lock\n /// redeemed BTC.\n /// @param amount Requested amount in satoshi. This is also the Bank balance\n /// that is taken from the `balanceOwner` upon request.\n /// Once the request is handled, the actual amount of BTC locked\n /// on the redeemer output script will be always lower than this value\n /// since the treasury and Bitcoin transaction fees must be incurred.\n /// The minimal amount satisfying the request can be computed as:\n /// `amount - (amount / redemptionTreasuryFeeDivisor) - redemptionTxMaxFee`.\n /// Fees values are taken at the moment of request creation.\n /// @dev Requirements:\n /// - Wallet behind `walletPubKeyHash` must be live,\n /// - `mainUtxo` components must point to the recent main UTXO\n /// of the given wallet, as currently known on the Ethereum chain,\n /// - `redeemerOutputScript` must be a proper Bitcoin script,\n /// - `redeemerOutputScript` cannot have wallet PKH as payload,\n /// - `amount` must be above or equal the `redemptionDustThreshold`,\n /// - Given `walletPubKeyHash` and `redeemerOutputScript` pair can be\n /// used for only one pending request at the same time,\n /// - Wallet must have enough Bitcoin balance to process the request,\n /// - Redeemer must make an allowance in the Bank that the Bridge\n /// contract can spend the given `amount`.\n function requestRedemption(\n bytes20 walletPubKeyHash,\n BitcoinTx.UTXO calldata mainUtxo,\n bytes calldata redeemerOutputScript,\n uint64 amount\n ) external {\n self.requestRedemption(\n walletPubKeyHash,\n mainUtxo,\n msg.sender,\n redeemerOutputScript,\n amount\n );\n }\n\n /// @notice Requests redemption of the given amount from the specified\n /// wallet to the redeemer Bitcoin output script. Used by\n /// `Bank.approveBalanceAndCall`. Can handle more complex cases\n /// where balance owner may be someone else than the redeemer.\n /// For example, vault redeeming its balance for some depositor.\n /// @param balanceOwner The address of the Bank balance owner whose balance\n /// is getting redeemed.\n /// @param amount Requested amount in satoshi. This is also the Bank balance\n /// that is taken from the `balanceOwner` upon request.\n /// Once the request is handled, the actual amount of BTC locked\n /// on the redeemer output script will be always lower than this value\n /// since the treasury and Bitcoin transaction fees must be incurred.\n /// The minimal amount satisfying the request can be computed as:\n /// `amount - (amount / redemptionTreasuryFeeDivisor) - redemptionTxMaxFee`.\n /// Fees values are taken at the moment of request creation.\n /// @param redemptionData ABI-encoded redemption data:\n /// [\n /// address redeemer,\n /// bytes20 walletPubKeyHash,\n /// bytes32 mainUtxoTxHash,\n /// uint32 mainUtxoTxOutputIndex,\n /// uint64 mainUtxoTxOutputValue,\n /// bytes redeemerOutputScript\n /// ]\n ///\n /// - redeemer: The Ethereum address of the redeemer who will be able\n /// to claim Bank balance if anything goes wrong during the redemption.\n /// In the most basic case, when someone redeems their balance\n /// from the Bank, `balanceOwner` is the same as `redeemer`.\n /// However, when a Vault is redeeming part of its balance for some\n /// redeemer address (for example, someone who has earlier deposited\n /// into that Vault), `balanceOwner` is the Vault, and `redeemer` is\n /// the address for which the vault is redeeming its balance to,\n /// - walletPubKeyHash: The 20-byte wallet public key hash (computed\n /// using Bitcoin HASH160 over the compressed ECDSA public key),\n /// - mainUtxoTxHash: Data of the wallet's main UTXO TX hash, as\n /// currently known on the Ethereum chain,\n /// - mainUtxoTxOutputIndex: Data of the wallet's main UTXO output\n /// index, as currently known on Ethereum chain,\n /// - mainUtxoTxOutputValue: Data of the wallet's main UTXO output\n /// value, as currently known on Ethereum chain,\n /// - redeemerOutputScript The redeemer's length-prefixed output\n /// script (P2PKH, P2WPKH, P2SH or P2WSH) that will be used to lock\n /// redeemed BTC.\n /// @dev Requirements:\n /// - The caller must be the Bank,\n /// - Wallet behind `walletPubKeyHash` must be live,\n /// - `mainUtxo` components must point to the recent main UTXO\n /// of the given wallet, as currently known on the Ethereum chain,\n /// - `redeemerOutputScript` must be a proper Bitcoin script,\n /// - `redeemerOutputScript` cannot have wallet PKH as payload,\n /// - `amount` must be above or equal the `redemptionDustThreshold`,\n /// - Given `walletPubKeyHash` and `redeemerOutputScript` pair can be\n /// used for only one pending request at the same time,\n /// - Wallet must have enough Bitcoin balance to process the request.\n ///\n /// Note on upgradeability:\n /// Bridge is an upgradeable contract deployed behind\n /// a TransparentUpgradeableProxy. Accepting redemption data as bytes\n /// provides great flexibility. The Bridge is just like any other\n /// contract with a balance approved in the Bank and can be upgraded\n /// to another version without being bound to a particular interface\n /// forever. This flexibility comes with the cost - developers\n /// integrating their vaults and dApps with `Bridge` using\n /// `approveBalanceAndCall` need to pay extra attention to\n /// `redemptionData` and adjust the code in case the expected structure\n /// of `redemptionData` changes.\n function receiveBalanceApproval(\n address balanceOwner,\n uint256 amount,\n bytes calldata redemptionData\n ) external override {\n require(msg.sender == address(self.bank), \"Caller is not the bank\");\n\n self.requestRedemption(\n balanceOwner,\n SafeCastUpgradeable.toUint64(amount),\n redemptionData\n );\n }\n\n /// @notice Used by the wallet to prove the BTC redemption transaction\n /// and to make the necessary bookkeeping. Redemption is only\n /// accepted if it satisfies SPV proof.\n ///\n /// The function is performing Bank balance updates by burning\n /// the total redeemed Bitcoin amount from Bridge balance and\n /// transferring the treasury fee sum to the treasury address.\n ///\n /// It is possible to prove the given redemption only one time.\n /// @param redemptionTx Bitcoin redemption transaction data.\n /// @param redemptionProof Bitcoin redemption proof data.\n /// @param mainUtxo Data of the wallet's main UTXO, as currently known on\n /// the Ethereum chain.\n /// @param walletPubKeyHash 20-byte public key hash (computed using Bitcoin\n /// HASH160 over the compressed ECDSA public key) of the wallet which\n /// performed the redemption transaction.\n /// @dev Requirements:\n /// - `redemptionTx` components must match the expected structure. See\n /// `BitcoinTx.Info` docs for reference. Their values must exactly\n /// correspond to appropriate Bitcoin transaction fields to produce\n /// a provable transaction hash,\n /// - The `redemptionTx` should represent a Bitcoin transaction with\n /// exactly 1 input that refers to the wallet's main UTXO. That\n /// transaction should have 1..n outputs handling existing pending\n /// redemption requests or pointing to reported timed out requests.\n /// There can be also 1 optional output representing the\n /// change and pointing back to the 20-byte wallet public key hash.\n /// The change should be always present if the redeemed value sum\n /// is lower than the total wallet's BTC balance,\n /// - `redemptionProof` components must match the expected structure.\n /// See `BitcoinTx.Proof` docs for reference. The `bitcoinHeaders`\n /// field must contain a valid number of block headers, not less\n /// than the `txProofDifficultyFactor` contract constant,\n /// - `mainUtxo` components must point to the recent main UTXO\n /// of the given wallet, as currently known on the Ethereum chain.\n /// Additionally, the recent main UTXO on Ethereum must be set,\n /// - `walletPubKeyHash` must be connected with the main UTXO used\n /// as transaction single input.\n /// Other remarks:\n /// - Putting the change output as the first transaction output can\n /// save some gas because the output processing loop begins each\n /// iteration by checking whether the given output is the change\n /// thus uses some gas for making the comparison. Once the change\n /// is identified, that check is omitted in further iterations.\n function submitRedemptionProof(\n BitcoinTx.Info calldata redemptionTx,\n BitcoinTx.Proof calldata redemptionProof,\n BitcoinTx.UTXO calldata mainUtxo,\n bytes20 walletPubKeyHash\n ) external onlySpvMaintainer {\n self.submitRedemptionProof(\n redemptionTx,\n redemptionProof,\n mainUtxo,\n walletPubKeyHash\n );\n }\n\n /// @notice Notifies that there is a pending redemption request associated\n /// with the given wallet, that has timed out. The redemption\n /// request is identified by the key built as\n /// `keccak256(keccak256(redeemerOutputScript) | walletPubKeyHash)`.\n /// The results of calling this function:\n /// - The pending redemptions value for the wallet will be decreased\n /// by the requested amount (minus treasury fee),\n /// - The tokens taken from the redeemer on redemption request will\n /// be returned to the redeemer,\n /// - The request will be moved from pending redemptions to\n /// timed-out redemptions,\n /// - If the state of the wallet is `Live` or `MovingFunds`, the\n /// wallet operators will be slashed and the notifier will be\n /// rewarded,\n /// - If the state of wallet is `Live`, the wallet will be closed or\n /// marked as `MovingFunds` (depending on the presence or absence\n /// of the wallet's main UTXO) and the wallet will no longer be\n /// marked as the active wallet (if it was marked as such).\n /// @param walletPubKeyHash 20-byte public key hash of the wallet.\n /// @param walletMembersIDs Identifiers of the wallet signing group members.\n /// @param redeemerOutputScript The redeemer's length-prefixed output\n /// script (P2PKH, P2WPKH, P2SH or P2WSH).\n /// @dev Requirements:\n /// - The wallet must be in the Live or MovingFunds or Terminated state,\n /// - The redemption request identified by `walletPubKeyHash` and\n /// `redeemerOutputScript` must exist,\n /// - The expression `keccak256(abi.encode(walletMembersIDs))` must\n /// be exactly the same as the hash stored under `membersIdsHash`\n /// for the given `walletID`. Those IDs are not directly stored\n /// in the contract for gas efficiency purposes but they can be\n /// read from appropriate `DkgResultSubmitted` and `DkgResultApproved`\n /// events of the `WalletRegistry` contract,\n /// - The amount of time defined by `redemptionTimeout` must have\n /// passed since the redemption was requested (the request must be\n /// timed-out).\n function notifyRedemptionTimeout(\n bytes20 walletPubKeyHash,\n uint32[] calldata walletMembersIDs,\n bytes calldata redeemerOutputScript\n ) external {\n self.notifyRedemptionTimeout(\n walletPubKeyHash,\n walletMembersIDs,\n redeemerOutputScript\n );\n }\n\n /// @notice Submits the moving funds target wallets commitment.\n /// Once all requirements are met, that function registers the\n /// target wallets commitment and opens the way for moving funds\n /// proof submission.\n /// The caller is reimbursed for the transaction costs.\n /// @param walletPubKeyHash 20-byte public key hash of the source wallet.\n /// @param walletMainUtxo Data of the source wallet's main UTXO, as\n /// currently known on the Ethereum chain.\n /// @param walletMembersIDs Identifiers of the source wallet signing group\n /// members.\n /// @param walletMemberIndex Position of the caller in the source wallet\n /// signing group members list.\n /// @param targetWallets List of 20-byte public key hashes of the target\n /// wallets that the source wallet commits to move the funds to.\n /// @dev Requirements:\n /// - The source wallet must be in the MovingFunds state,\n /// - The source wallet must not have pending redemption requests,\n /// - The source wallet must not have pending moved funds sweep requests,\n /// - The source wallet must not have submitted its commitment already,\n /// - The expression `keccak256(abi.encode(walletMembersIDs))` must\n /// be exactly the same as the hash stored under `membersIdsHash`\n /// for the given source wallet in the ECDSA registry. Those IDs are\n /// not directly stored in the contract for gas efficiency purposes\n /// but they can be read from appropriate `DkgResultSubmitted`\n /// and `DkgResultApproved` events,\n /// - The `walletMemberIndex` must be in range [1, walletMembersIDs.length],\n /// - The caller must be the member of the source wallet signing group\n /// at the position indicated by `walletMemberIndex` parameter,\n /// - The `walletMainUtxo` components must point to the recent main\n /// UTXO of the source wallet, as currently known on the Ethereum\n /// chain,\n /// - Source wallet BTC balance must be greater than zero,\n /// - At least one Live wallet must exist in the system,\n /// - Submitted target wallets count must match the expected count\n /// `N = min(liveWalletsCount, ceil(walletBtcBalance / walletMaxBtcTransfer))`\n /// where `N > 0`,\n /// - Each target wallet must be not equal to the source wallet,\n /// - Each target wallet must follow the expected order i.e. all\n /// target wallets 20-byte public key hashes represented as numbers\n /// must form a strictly increasing sequence without duplicates,\n /// - Each target wallet must be in Live state.\n function submitMovingFundsCommitment(\n bytes20 walletPubKeyHash,\n BitcoinTx.UTXO calldata walletMainUtxo,\n uint32[] calldata walletMembersIDs,\n uint256 walletMemberIndex,\n bytes20[] calldata targetWallets\n ) external {\n uint256 gasStart = gasleft();\n\n self.submitMovingFundsCommitment(\n walletPubKeyHash,\n walletMainUtxo,\n walletMembersIDs,\n walletMemberIndex,\n targetWallets\n );\n\n self.reimbursementPool.refund(\n (gasStart - gasleft()) + self.movingFundsCommitmentGasOffset,\n msg.sender\n );\n }\n\n /// @notice Resets the moving funds timeout for the given wallet if the\n /// target wallet commitment cannot be submitted due to a lack\n /// of live wallets in the system.\n /// @param walletPubKeyHash 20-byte public key hash of the moving funds wallet.\n /// @dev Requirements:\n /// - The wallet must be in the MovingFunds state,\n /// - The target wallets commitment must not be already submitted for\n /// the given moving funds wallet,\n /// - Live wallets count must be zero,\n /// - The moving funds timeout reset delay must be elapsed.\n function resetMovingFundsTimeout(bytes20 walletPubKeyHash) external {\n self.resetMovingFundsTimeout(walletPubKeyHash);\n }\n\n /// @notice Used by the wallet to prove the BTC moving funds transaction\n /// and to make the necessary state changes. Moving funds is only\n /// accepted if it satisfies SPV proof.\n ///\n /// The function validates the moving funds transaction structure\n /// by checking if it actually spends the main UTXO of the declared\n /// wallet and locks the value on the pre-committed target wallets\n /// using a reasonable transaction fee. If all preconditions are\n /// met, this functions closes the source wallet.\n ///\n /// It is possible to prove the given moving funds transaction only\n /// one time.\n /// @param movingFundsTx Bitcoin moving funds transaction data.\n /// @param movingFundsProof Bitcoin moving funds proof data.\n /// @param mainUtxo Data of the wallet's main UTXO, as currently known on\n /// the Ethereum chain.\n /// @param walletPubKeyHash 20-byte public key hash (computed using Bitcoin\n /// HASH160 over the compressed ECDSA public key) of the wallet\n /// which performed the moving funds transaction.\n /// @dev Requirements:\n /// - `movingFundsTx` components must match the expected structure. See\n /// `BitcoinTx.Info` docs for reference. Their values must exactly\n /// correspond to appropriate Bitcoin transaction fields to produce\n /// a provable transaction hash,\n /// - The `movingFundsTx` should represent a Bitcoin transaction with\n /// exactly 1 input that refers to the wallet's main UTXO. That\n /// transaction should have 1..n outputs corresponding to the\n /// pre-committed target wallets. Outputs must be ordered in the\n /// same way as their corresponding target wallets are ordered\n /// within the target wallets commitment,\n /// - `movingFundsProof` components must match the expected structure.\n /// See `BitcoinTx.Proof` docs for reference. The `bitcoinHeaders`\n /// field must contain a valid number of block headers, not less\n /// than the `txProofDifficultyFactor` contract constant,\n /// - `mainUtxo` components must point to the recent main UTXO\n /// of the given wallet, as currently known on the Ethereum chain.\n /// Additionally, the recent main UTXO on Ethereum must be set,\n /// - `walletPubKeyHash` must be connected with the main UTXO used\n /// as transaction single input,\n /// - The wallet that `walletPubKeyHash` points to must be in the\n /// MovingFunds state,\n /// - The target wallets commitment must be submitted by the wallet\n /// that `walletPubKeyHash` points to,\n /// - The total Bitcoin transaction fee must be lesser or equal\n /// to `movingFundsTxMaxTotalFee` governable parameter.\n function submitMovingFundsProof(\n BitcoinTx.Info calldata movingFundsTx,\n BitcoinTx.Proof calldata movingFundsProof,\n BitcoinTx.UTXO calldata mainUtxo,\n bytes20 walletPubKeyHash\n ) external onlySpvMaintainer {\n self.submitMovingFundsProof(\n movingFundsTx,\n movingFundsProof,\n mainUtxo,\n walletPubKeyHash\n );\n }\n\n /// @notice Notifies about a timed out moving funds process. Terminates\n /// the wallet and slashes signing group members as a result.\n /// @param walletPubKeyHash 20-byte public key hash of the wallet.\n /// @param walletMembersIDs Identifiers of the wallet signing group members.\n /// @dev Requirements:\n /// - The wallet must be in the MovingFunds state,\n /// - The moving funds timeout must be actually exceeded,\n /// - The expression `keccak256(abi.encode(walletMembersIDs))` must\n /// be exactly the same as the hash stored under `membersIdsHash`\n /// for the given `walletID`. Those IDs are not directly stored\n /// in the contract for gas efficiency purposes but they can be\n /// read from appropriate `DkgResultSubmitted` and `DkgResultApproved`\n /// events of the `WalletRegistry` contract.\n function notifyMovingFundsTimeout(\n bytes20 walletPubKeyHash,\n uint32[] calldata walletMembersIDs\n ) external {\n self.notifyMovingFundsTimeout(walletPubKeyHash, walletMembersIDs);\n }\n\n /// @notice Notifies about a moving funds wallet whose BTC balance is\n /// below the moving funds dust threshold. Ends the moving funds\n /// process and begins wallet closing immediately.\n /// @param walletPubKeyHash 20-byte public key hash of the wallet\n /// @param mainUtxo Data of the wallet's main UTXO, as currently known\n /// on the Ethereum chain.\n /// @dev Requirements:\n /// - The wallet must be in the MovingFunds state,\n /// - The `mainUtxo` components must point to the recent main UTXO\n /// of the given wallet, as currently known on the Ethereum chain.\n /// If the wallet has no main UTXO, this parameter can be empty as it\n /// is ignored,\n /// - The wallet BTC balance must be below the moving funds threshold.\n function notifyMovingFundsBelowDust(\n bytes20 walletPubKeyHash,\n BitcoinTx.UTXO calldata mainUtxo\n ) external {\n self.notifyMovingFundsBelowDust(walletPubKeyHash, mainUtxo);\n }\n\n /// @notice Used by the wallet to prove the BTC moved funds sweep\n /// transaction and to make the necessary state changes. Moved\n /// funds sweep is only accepted if it satisfies SPV proof.\n ///\n /// The function validates the sweep transaction structure by\n /// checking if it actually spends the moved funds UTXO and the\n /// sweeping wallet's main UTXO (optionally), and if it locks the\n /// value on the sweeping wallet's 20-byte public key hash using a\n /// reasonable transaction fee. If all preconditions are\n /// met, this function updates the sweeping wallet main UTXO, thus\n /// their BTC balance.\n ///\n /// It is possible to prove the given sweep transaction only\n /// one time.\n /// @param sweepTx Bitcoin sweep funds transaction data.\n /// @param sweepProof Bitcoin sweep funds proof data.\n /// @param mainUtxo Data of the sweeping wallet's main UTXO, as currently\n /// known on the Ethereum chain.\n /// @dev Requirements:\n /// - `sweepTx` components must match the expected structure. See\n /// `BitcoinTx.Info` docs for reference. Their values must exactly\n /// correspond to appropriate Bitcoin transaction fields to produce\n /// a provable transaction hash,\n /// - The `sweepTx` should represent a Bitcoin transaction with\n /// the first input pointing to a moved funds sweep request targeted\n /// to the wallet, and optionally, the second input pointing to the\n /// wallet's main UTXO, if the sweeping wallet has a main UTXO set.\n /// There should be only one output locking funds on the sweeping\n /// wallet 20-byte public key hash,\n /// - `sweepProof` components must match the expected structure.\n /// See `BitcoinTx.Proof` docs for reference. The `bitcoinHeaders`\n /// field must contain a valid number of block headers, not less\n /// than the `txProofDifficultyFactor` contract constant,\n /// - `mainUtxo` components must point to the recent main UTXO\n /// of the sweeping wallet, as currently known on the Ethereum chain.\n /// If there is no main UTXO, this parameter is ignored,\n /// - The sweeping wallet must be in the Live or MovingFunds state,\n /// - The total Bitcoin transaction fee must be lesser or equal\n /// to `movedFundsSweepTxMaxTotalFee` governable parameter.\n function submitMovedFundsSweepProof(\n BitcoinTx.Info calldata sweepTx,\n BitcoinTx.Proof calldata sweepProof,\n BitcoinTx.UTXO calldata mainUtxo\n ) external onlySpvMaintainer {\n self.submitMovedFundsSweepProof(sweepTx, sweepProof, mainUtxo);\n }\n\n /// @notice Notifies about a timed out moved funds sweep process. If the\n /// wallet is not terminated yet, that function terminates\n /// the wallet and slashes signing group members as a result.\n /// Marks the given sweep request as TimedOut.\n /// @param movingFundsTxHash 32-byte hash of the moving funds transaction\n /// that caused the sweep request to be created.\n /// @param movingFundsTxOutputIndex Index of the moving funds transaction\n /// output that is subject of the sweep request.\n /// @param walletMembersIDs Identifiers of the wallet signing group members.\n /// @dev Requirements:\n /// - The moved funds sweep request must be in the Pending state,\n /// - The moved funds sweep timeout must be actually exceeded,\n /// - The wallet must be either in the Live or MovingFunds or\n /// Terminated state,\n /// - The expression `keccak256(abi.encode(walletMembersIDs))` must\n /// be exactly the same as the hash stored under `membersIdsHash`\n /// for the given `walletID`. Those IDs are not directly stored\n /// in the contract for gas efficiency purposes but they can be\n /// read from appropriate `DkgResultSubmitted` and `DkgResultApproved`\n /// events of the `WalletRegistry` contract.\n function notifyMovedFundsSweepTimeout(\n bytes32 movingFundsTxHash,\n uint32 movingFundsTxOutputIndex,\n uint32[] calldata walletMembersIDs\n ) external {\n self.notifyMovedFundsSweepTimeout(\n movingFundsTxHash,\n movingFundsTxOutputIndex,\n walletMembersIDs\n );\n }\n\n /// @notice Requests creation of a new wallet. This function just\n /// forms a request and the creation process is performed\n /// asynchronously. Once a wallet is created, the ECDSA Wallet\n /// Registry will notify this contract by calling the\n /// `__ecdsaWalletCreatedCallback` function.\n /// @param activeWalletMainUtxo Data of the active wallet's main UTXO, as\n /// currently known on the Ethereum chain.\n /// @dev Requirements:\n /// - `activeWalletMainUtxo` components must point to the recent main\n /// UTXO of the given active wallet, as currently known on the\n /// Ethereum chain. If there is no active wallet at the moment, or\n /// the active wallet has no main UTXO, this parameter can be\n /// empty as it is ignored,\n /// - Wallet creation must not be in progress,\n /// - If the active wallet is set, one of the following\n /// conditions must be true:\n /// - The active wallet BTC balance is above the minimum threshold\n /// and the active wallet is old enough, i.e. the creation period\n /// was elapsed since its creation time,\n /// - The active wallet BTC balance is above the maximum threshold.\n function requestNewWallet(BitcoinTx.UTXO calldata activeWalletMainUtxo)\n external\n {\n self.requestNewWallet(activeWalletMainUtxo);\n }\n\n /// @notice A callback function that is called by the ECDSA Wallet Registry\n /// once a new ECDSA wallet is created.\n /// @param ecdsaWalletID Wallet's unique identifier.\n /// @param publicKeyX Wallet's public key's X coordinate.\n /// @param publicKeyY Wallet's public key's Y coordinate.\n /// @dev Requirements:\n /// - The only caller authorized to call this function is `registry`,\n /// - Given wallet data must not belong to an already registered wallet.\n function __ecdsaWalletCreatedCallback(\n bytes32 ecdsaWalletID,\n bytes32 publicKeyX,\n bytes32 publicKeyY\n ) external override {\n self.registerNewWallet(ecdsaWalletID, publicKeyX, publicKeyY);\n }\n\n /// @notice A callback function that is called by the ECDSA Wallet Registry\n /// once a wallet heartbeat failure is detected.\n /// @param publicKeyX Wallet's public key's X coordinate.\n /// @param publicKeyY Wallet's public key's Y coordinate.\n /// @dev Requirements:\n /// - The only caller authorized to call this function is `registry`,\n /// - Wallet must be in Live state.\n function __ecdsaWalletHeartbeatFailedCallback(\n bytes32,\n bytes32 publicKeyX,\n bytes32 publicKeyY\n ) external override {\n self.notifyWalletHeartbeatFailed(publicKeyX, publicKeyY);\n }\n\n /// @notice Notifies that the wallet is either old enough or has too few\n /// satoshi left and qualifies to be closed.\n /// @param walletPubKeyHash 20-byte public key hash of the wallet.\n /// @param walletMainUtxo Data of the wallet's main UTXO, as currently\n /// known on the Ethereum chain.\n /// @dev Requirements:\n /// - Wallet must not be set as the current active wallet,\n /// - Wallet must exceed the wallet maximum age OR the wallet BTC\n /// balance must be lesser than the minimum threshold. If the latter\n /// case is true, the `walletMainUtxo` components must point to the\n /// recent main UTXO of the given wallet, as currently known on the\n /// Ethereum chain. If the wallet has no main UTXO, this parameter\n /// can be empty as it is ignored since the wallet balance is\n /// assumed to be zero,\n /// - Wallet must be in Live state.\n function notifyWalletCloseable(\n bytes20 walletPubKeyHash,\n BitcoinTx.UTXO calldata walletMainUtxo\n ) external {\n self.notifyWalletCloseable(walletPubKeyHash, walletMainUtxo);\n }\n\n /// @notice Notifies about the end of the closing period for the given wallet.\n /// Closes the wallet ultimately and notifies the ECDSA registry\n /// about this fact.\n /// @param walletPubKeyHash 20-byte public key hash of the wallet.\n /// @dev Requirements:\n /// - The wallet must be in the Closing state,\n /// - The wallet closing period must have elapsed.\n function notifyWalletClosingPeriodElapsed(bytes20 walletPubKeyHash)\n external\n {\n self.notifyWalletClosingPeriodElapsed(walletPubKeyHash);\n }\n\n /// @notice Submits a fraud challenge indicating that a UTXO being under\n /// wallet control was unlocked by the wallet but was not used\n /// according to the protocol rules. That means the wallet signed\n /// a transaction input pointing to that UTXO and there is a unique\n /// sighash and signature pair associated with that input. This\n /// function uses those parameters to create a fraud accusation that\n /// proves a given transaction input unlocking the given UTXO was\n /// actually signed by the wallet. This function cannot determine\n /// whether the transaction was actually broadcast and the input was\n /// consumed in a fraudulent way so it just opens a challenge period\n /// during which the wallet can defeat the challenge by submitting\n /// proof of a transaction that consumes the given input according\n /// to protocol rules. To prevent spurious allegations, the caller\n /// must deposit ETH that is returned back upon justified fraud\n /// challenge or confiscated otherwise.\n /// @param walletPublicKey The public key of the wallet in the uncompressed\n /// and unprefixed format (64 bytes).\n /// @param preimageSha256 The hash that was generated by applying SHA-256\n /// one time over the preimage used during input signing. The preimage\n /// is a serialized subset of the transaction and its structure\n /// depends on the transaction input (see BIP-143 for reference).\n /// Notice that applying SHA-256 over the `preimageSha256` results\n /// in `sighash`. The path from `preimage` to `sighash` looks like\n /// this:\n /// preimage -> (SHA-256) -> preimageSha256 -> (SHA-256) -> sighash.\n /// @param signature Bitcoin signature in the R/S/V format.\n /// @dev Requirements:\n /// - Wallet behind `walletPublicKey` must be in Live or MovingFunds\n /// or Closing state,\n /// - The challenger must send appropriate amount of ETH used as\n /// fraud challenge deposit,\n /// - The signature (represented by r, s and v) must be generated by\n /// the wallet behind `walletPubKey` during signing of `sighash`\n /// which was calculated from `preimageSha256`,\n /// - Wallet can be challenged for the given signature only once.\n function submitFraudChallenge(\n bytes calldata walletPublicKey,\n bytes memory preimageSha256,\n BitcoinTx.RSVSignature calldata signature\n ) external payable {\n self.submitFraudChallenge(walletPublicKey, preimageSha256, signature);\n }\n\n /// @notice Allows to defeat a pending fraud challenge against a wallet if\n /// the transaction that spends the UTXO follows the protocol rules.\n /// In order to defeat the challenge the same `walletPublicKey` and\n /// signature (represented by `r`, `s` and `v`) must be provided as\n /// were used to calculate the sighash during input signing.\n /// The fraud challenge defeat attempt will only succeed if the\n /// inputs in the preimage are considered honestly spent by the\n /// wallet. Therefore the transaction spending the UTXO must be\n /// proven in the Bridge before a challenge defeat is called.\n /// If successfully defeated, the fraud challenge is marked as\n /// resolved and the amount of ether deposited by the challenger is\n /// sent to the treasury.\n /// @param walletPublicKey The public key of the wallet in the uncompressed\n /// and unprefixed format (64 bytes).\n /// @param preimage The preimage which produces sighash used to generate the\n /// ECDSA signature that is the subject of the fraud claim. It is a\n /// serialized subset of the transaction. The exact subset used as\n /// the preimage depends on the transaction input the signature is\n /// produced for. See BIP-143 for reference.\n /// @param witness Flag indicating whether the preimage was produced for a\n /// witness input. True for witness, false for non-witness input.\n /// @dev Requirements:\n /// - `walletPublicKey` and `sighash` calculated as `hash256(preimage)`\n /// must identify an open fraud challenge,\n /// - the preimage must be a valid preimage of a transaction generated\n /// according to the protocol rules and already proved in the Bridge,\n /// - before a defeat attempt is made the transaction that spends the\n /// given UTXO must be proven in the Bridge.\n function defeatFraudChallenge(\n bytes calldata walletPublicKey,\n bytes calldata preimage,\n bool witness\n ) external {\n self.defeatFraudChallenge(walletPublicKey, preimage, witness);\n }\n\n /// @notice Allows to defeat a pending fraud challenge against a wallet by\n /// proving the sighash and signature were produced for an off-chain\n /// wallet heartbeat message following a strict format.\n /// In order to defeat the challenge the same `walletPublicKey` and\n /// signature (represented by `r`, `s` and `v`) must be provided as\n /// were used to calculate the sighash during heartbeat message\n /// signing. The fraud challenge defeat attempt will only succeed if\n /// the signed message follows a strict format required for\n /// heartbeat messages. If successfully defeated, the fraud\n /// challenge is marked as resolved and the amount of ether\n /// deposited by the challenger is sent to the treasury.\n /// @param walletPublicKey The public key of the wallet in the uncompressed\n /// and unprefixed format (64 bytes).\n /// @param heartbeatMessage Off-chain heartbeat message meeting the heartbeat\n /// message format requirements which produces sighash used to\n /// generate the ECDSA signature that is the subject of the fraud\n /// claim.\n /// @dev Requirements:\n /// - `walletPublicKey` and `sighash` calculated as\n /// `hash256(heartbeatMessage)` must identify an open fraud challenge,\n /// - `heartbeatMessage` must follow a strict format of heartbeat\n /// messages.\n function defeatFraudChallengeWithHeartbeat(\n bytes calldata walletPublicKey,\n bytes calldata heartbeatMessage\n ) external {\n self.defeatFraudChallengeWithHeartbeat(\n walletPublicKey,\n heartbeatMessage\n );\n }\n\n /// @notice Notifies about defeat timeout for the given fraud challenge.\n /// Can be called only if there was a fraud challenge identified by\n /// the provided `walletPublicKey` and `sighash` and it was not\n /// defeated on time. The amount of time that needs to pass after\n /// a fraud challenge is reported is indicated by the\n /// `challengeDefeatTimeout`. After a successful fraud challenge\n /// defeat timeout notification the fraud challenge is marked as\n /// resolved, the stake of each operator is slashed, the ether\n /// deposited is returned to the challenger and the challenger is\n /// rewarded.\n /// @param walletPublicKey The public key of the wallet in the uncompressed\n /// and unprefixed format (64 bytes).\n /// @param walletMembersIDs Identifiers of the wallet signing group members.\n /// @param preimageSha256 The hash that was generated by applying SHA-256\n /// one time over the preimage used during input signing. The preimage\n /// is a serialized subset of the transaction and its structure\n /// depends on the transaction input (see BIP-143 for reference).\n /// Notice that applying SHA-256 over the `preimageSha256` results\n /// in `sighash`. The path from `preimage` to `sighash` looks like\n /// this:\n /// preimage -> (SHA-256) -> preimageSha256 -> (SHA-256) -> sighash.\n /// @dev Requirements:\n /// - The wallet must be in the Live or MovingFunds or Closing or\n /// Terminated state,\n /// - The `walletPublicKey` and `sighash` calculated from\n /// `preimageSha256` must identify an open fraud challenge,\n /// - The expression `keccak256(abi.encode(walletMembersIDs))` must\n /// be exactly the same as the hash stored under `membersIdsHash`\n /// for the given `walletID`. Those IDs are not directly stored\n /// in the contract for gas efficiency purposes but they can be\n /// read from appropriate `DkgResultSubmitted` and `DkgResultApproved`\n /// events of the `WalletRegistry` contract,\n /// - The amount of time indicated by `challengeDefeatTimeout` must pass\n /// after the challenge was reported.\n function notifyFraudChallengeDefeatTimeout(\n bytes calldata walletPublicKey,\n uint32[] calldata walletMembersIDs,\n bytes memory preimageSha256\n ) external {\n self.notifyFraudChallengeDefeatTimeout(\n walletPublicKey,\n walletMembersIDs,\n preimageSha256\n );\n }\n\n /// @notice Allows the Governance to mark the given vault address as trusted\n /// or no longer trusted. Vaults are not trusted by default.\n /// Trusted vault must meet the following criteria:\n /// - `IVault.receiveBalanceIncrease` must have a known, low gas\n /// cost,\n /// - `IVault.receiveBalanceIncrease` must never revert.\n /// @dev Without restricting reveal only to trusted vaults, malicious\n /// vaults not meeting the criteria would be able to nuke sweep proof\n /// transactions executed by ECDSA wallet with deposits routed to\n /// them.\n /// @param vault The address of the vault.\n /// @param isTrusted flag indicating whether the vault is trusted or not.\n /// @dev Can only be called by the Governance.\n function setVaultStatus(address vault, bool isTrusted)\n external\n onlyGovernance\n {\n self.isVaultTrusted[vault] = isTrusted;\n emit VaultStatusUpdated(vault, isTrusted);\n }\n\n /// @notice Allows the Governance to mark the given address as trusted\n /// or no longer trusted SPV maintainer. Addresses are not trusted\n /// as SPV maintainers by default.\n /// @dev The SPV proof does not check whether the transaction is a part of\n /// the Bitcoin mainnet, it only checks whether the transaction has been\n /// mined performing the required amount of work as on Bitcoin mainnet.\n /// The possibility of submitting SPV proofs is limited to trusted SPV\n /// maintainers. The system expects transaction confirmations with the\n /// required work accumulated, so trusted SPV maintainers can not prove\n /// the transaction without providing the required Bitcoin proof of work.\n /// Trusted maintainers address the issue of an economic game between\n /// tBTC and Bitcoin mainnet where large Bitcoin mining pools can decide\n /// to use their hash power to mine fake Bitcoin blocks to prove them in\n /// tBTC instead of receiving Bitcoin miner rewards.\n /// @param spvMaintainer The address of the SPV maintainer.\n /// @param isTrusted flag indicating whether the address is trusted or not.\n /// @dev Can only be called by the Governance.\n function setSpvMaintainerStatus(address spvMaintainer, bool isTrusted)\n external\n onlyGovernance\n {\n self.isSpvMaintainer[spvMaintainer] = isTrusted;\n emit SpvMaintainerStatusUpdated(spvMaintainer, isTrusted);\n }\n\n /// @notice Updates parameters of deposits.\n /// @param depositDustThreshold New value of the deposit dust threshold in\n /// satoshis. It is the minimal amount that can be requested to\n //// deposit. Value of this parameter must take into account the value\n /// of `depositTreasuryFeeDivisor` and `depositTxMaxFee` parameters\n /// in order to make requests that can incur the treasury and\n /// transaction fee and still satisfy the depositor.\n /// @param depositTreasuryFeeDivisor New value of the treasury fee divisor.\n /// It is the divisor used to compute the treasury fee taken from\n /// each deposit and transferred to the treasury upon sweep proof\n /// submission. That fee is computed as follows:\n /// `treasuryFee = depositedAmount / depositTreasuryFeeDivisor`\n /// For example, if the treasury fee needs to be 2% of each deposit,\n /// the `depositTreasuryFeeDivisor` should be set to `50`\n /// because `1/50 = 0.02 = 2%`.\n /// @param depositTxMaxFee New value of the deposit tx max fee in satoshis.\n /// It is the maximum amount of BTC transaction fee that can\n /// be incurred by each swept deposit being part of the given sweep\n /// transaction. If the maximum BTC transaction fee is exceeded,\n /// such transaction is considered a fraud.\n /// @param depositRevealAheadPeriod New value of the deposit reveal ahead\n /// period parameter in seconds. It defines the length of the period\n /// that must be preserved between the deposit reveal time and the\n /// deposit refund locktime.\n /// @dev Requirements:\n /// - Deposit dust threshold must be greater than zero,\n /// - Deposit dust threshold must be greater than deposit TX max fee,\n /// - Deposit transaction max fee must be greater than zero.\n function updateDepositParameters(\n uint64 depositDustThreshold,\n uint64 depositTreasuryFeeDivisor,\n uint64 depositTxMaxFee,\n uint32 depositRevealAheadPeriod\n ) external onlyGovernance {\n self.updateDepositParameters(\n depositDustThreshold,\n depositTreasuryFeeDivisor,\n depositTxMaxFee,\n depositRevealAheadPeriod\n );\n }\n\n /// @notice Updates parameters of redemptions.\n /// @param redemptionDustThreshold New value of the redemption dust\n /// threshold in satoshis. It is the minimal amount that can be\n /// requested for redemption. Value of this parameter must take into\n /// account the value of `redemptionTreasuryFeeDivisor` and\n /// `redemptionTxMaxFee` parameters in order to make requests that\n /// can incur the treasury and transaction fee and still satisfy the\n /// redeemer.\n /// @param redemptionTreasuryFeeDivisor New value of the redemption\n /// treasury fee divisor. It is the divisor used to compute the\n /// treasury fee taken from each redemption request and transferred\n /// to the treasury upon successful request finalization. That fee is\n /// computed as follows:\n /// `treasuryFee = requestedAmount / redemptionTreasuryFeeDivisor`\n /// For example, if the treasury fee needs to be 2% of each\n /// redemption request, the `redemptionTreasuryFeeDivisor` should\n /// be set to `50` because `1/50 = 0.02 = 2%`.\n /// @param redemptionTxMaxFee New value of the redemption transaction max\n /// fee in satoshis. It is the maximum amount of BTC transaction fee\n /// that can be incurred by each redemption request being part of the\n /// given redemption transaction. If the maximum BTC transaction fee\n /// is exceeded, such transaction is considered a fraud.\n /// This is a per-redemption output max fee for the redemption\n /// transaction.\n /// @param redemptionTxMaxTotalFee New value of the redemption transaction\n /// max total fee in satoshis. It is the maximum amount of the total\n /// BTC transaction fee that is acceptable in a single redemption\n /// transaction. This is a _total_ max fee for the entire redemption\n /// transaction.\n /// @param redemptionTimeout New value of the redemption timeout in seconds.\n /// It is the time after which the redemption request can be reported\n /// as timed out. It is counted from the moment when the redemption\n /// request was created via `requestRedemption` call. Reported timed\n /// out requests are cancelled and locked balance is returned to the\n /// redeemer in full amount.\n /// @param redemptionTimeoutSlashingAmount New value of the redemption\n /// timeout slashing amount in T, it is the amount slashed from each\n /// wallet member for redemption timeout.\n /// @param redemptionTimeoutNotifierRewardMultiplier New value of the\n /// redemption timeout notifier reward multiplier as percentage,\n /// it determines the percentage of the notifier reward from the\n /// staking contact the notifier of a redemption timeout receives.\n /// The value must be in the range [0, 100].\n /// @dev Requirements:\n /// - Redemption dust threshold must be greater than moving funds dust\n /// threshold,\n /// - Redemption dust threshold must be greater than the redemption TX\n /// max fee,\n /// - Redemption transaction max fee must be greater than zero,\n /// - Redemption transaction max total fee must be greater than or\n /// equal to the redemption transaction per-request max fee,\n /// - Redemption timeout must be greater than zero,\n /// - Redemption timeout notifier reward multiplier must be in the\n /// range [0, 100].\n function updateRedemptionParameters(\n uint64 redemptionDustThreshold,\n uint64 redemptionTreasuryFeeDivisor,\n uint64 redemptionTxMaxFee,\n uint64 redemptionTxMaxTotalFee,\n uint32 redemptionTimeout,\n uint96 redemptionTimeoutSlashingAmount,\n uint32 redemptionTimeoutNotifierRewardMultiplier\n ) external onlyGovernance {\n self.updateRedemptionParameters(\n redemptionDustThreshold,\n redemptionTreasuryFeeDivisor,\n redemptionTxMaxFee,\n redemptionTxMaxTotalFee,\n redemptionTimeout,\n redemptionTimeoutSlashingAmount,\n redemptionTimeoutNotifierRewardMultiplier\n );\n }\n\n /// @notice Updates parameters of moving funds.\n /// @param movingFundsTxMaxTotalFee New value of the moving funds transaction\n /// max total fee in satoshis. It is the maximum amount of the total\n /// BTC transaction fee that is acceptable in a single moving funds\n /// transaction. This is a _total_ max fee for the entire moving\n /// funds transaction.\n /// @param movingFundsDustThreshold New value of the moving funds dust\n /// threshold. It is the minimal satoshi amount that makes sense to\n /// be transferred during the moving funds process. Moving funds\n /// wallets having their BTC balance below that value can begin\n /// closing immediately as transferring such a low value may not be\n /// possible due to BTC network fees.\n /// @param movingFundsTimeoutResetDelay New value of the moving funds\n /// timeout reset delay in seconds. It is the time after which the\n /// moving funds timeout can be reset in case the target wallet\n /// commitment cannot be submitted due to a lack of live wallets\n /// in the system. It is counted from the moment when the wallet\n /// was requested to move their funds and switched to the MovingFunds\n /// state or from the moment the timeout was reset the last time.\n /// @param movingFundsTimeout New value of the moving funds timeout in\n /// seconds. It is the time after which the moving funds process can\n /// be reported as timed out. It is counted from the moment when the\n /// wallet was requested to move their funds and switched to the\n /// MovingFunds state.\n /// @param movingFundsTimeoutSlashingAmount New value of the moving funds\n /// timeout slashing amount in T, it is the amount slashed from each\n /// wallet member for moving funds timeout.\n /// @param movingFundsTimeoutNotifierRewardMultiplier New value of the\n /// moving funds timeout notifier reward multiplier as percentage,\n /// it determines the percentage of the notifier reward from the\n /// staking contact the notifier of a moving funds timeout receives.\n /// The value must be in the range [0, 100].\n /// @param movingFundsCommitmentGasOffset New value of the gas offset for\n /// moving funds target wallet commitment transaction gas costs\n /// reimbursement.\n /// @param movedFundsSweepTxMaxTotalFee New value of the moved funds sweep\n /// transaction max total fee in satoshis. It is the maximum amount\n /// of the total BTC transaction fee that is acceptable in a single\n /// moved funds sweep transaction. This is a _total_ max fee for the\n /// entire moved funds sweep transaction.\n /// @param movedFundsSweepTimeout New value of the moved funds sweep\n /// timeout in seconds. It is the time after which the moved funds\n /// sweep process can be reported as timed out. It is counted from\n /// the moment when the wallet was requested to sweep the received\n /// funds.\n /// @param movedFundsSweepTimeoutSlashingAmount New value of the moved\n /// funds sweep timeout slashing amount in T, it is the amount\n /// slashed from each wallet member for moved funds sweep timeout.\n /// @param movedFundsSweepTimeoutNotifierRewardMultiplier New value of\n /// the moved funds sweep timeout notifier reward multiplier as\n /// percentage, it determines the percentage of the notifier reward\n /// from the staking contact the notifier of a moved funds sweep\n /// timeout receives. The value must be in the range [0, 100].\n /// @dev Requirements:\n /// - Moving funds transaction max total fee must be greater than zero,\n /// - Moving funds dust threshold must be greater than zero and lower\n /// than the redemption dust threshold,\n /// - Moving funds timeout reset delay must be greater than zero,\n /// - Moving funds timeout must be greater than the moving funds\n /// timeout reset delay,\n /// - Moving funds timeout notifier reward multiplier must be in the\n /// range [0, 100],\n /// - Moved funds sweep transaction max total fee must be greater than zero,\n /// - Moved funds sweep timeout must be greater than zero,\n /// - Moved funds sweep timeout notifier reward multiplier must be in the\n /// range [0, 100].\n function updateMovingFundsParameters(\n uint64 movingFundsTxMaxTotalFee,\n uint64 movingFundsDustThreshold,\n uint32 movingFundsTimeoutResetDelay,\n uint32 movingFundsTimeout,\n uint96 movingFundsTimeoutSlashingAmount,\n uint32 movingFundsTimeoutNotifierRewardMultiplier,\n uint16 movingFundsCommitmentGasOffset,\n uint64 movedFundsSweepTxMaxTotalFee,\n uint32 movedFundsSweepTimeout,\n uint96 movedFundsSweepTimeoutSlashingAmount,\n uint32 movedFundsSweepTimeoutNotifierRewardMultiplier\n ) external onlyGovernance {\n self.updateMovingFundsParameters(\n movingFundsTxMaxTotalFee,\n movingFundsDustThreshold,\n movingFundsTimeoutResetDelay,\n movingFundsTimeout,\n movingFundsTimeoutSlashingAmount,\n movingFundsTimeoutNotifierRewardMultiplier,\n movingFundsCommitmentGasOffset,\n movedFundsSweepTxMaxTotalFee,\n movedFundsSweepTimeout,\n movedFundsSweepTimeoutSlashingAmount,\n movedFundsSweepTimeoutNotifierRewardMultiplier\n );\n }\n\n /// @notice Updates parameters of wallets.\n /// @param walletCreationPeriod New value of the wallet creation period in\n /// seconds, determines how frequently a new wallet creation can be\n /// requested.\n /// @param walletCreationMinBtcBalance New value of the wallet minimum BTC\n /// balance in satoshi, used to decide about wallet creation.\n /// @param walletCreationMaxBtcBalance New value of the wallet maximum BTC\n /// balance in satoshi, used to decide about wallet creation.\n /// @param walletClosureMinBtcBalance New value of the wallet minimum BTC\n /// balance in satoshi, used to decide about wallet closure.\n /// @param walletMaxAge New value of the wallet maximum age in seconds,\n /// indicates the maximum age of a wallet in seconds, after which\n /// the wallet moving funds process can be requested.\n /// @param walletMaxBtcTransfer New value of the wallet maximum BTC transfer\n /// in satoshi, determines the maximum amount that can be transferred\n // to a single target wallet during the moving funds process.\n /// @param walletClosingPeriod New value of the wallet closing period in\n /// seconds, determines the length of the wallet closing period,\n // i.e. the period when the wallet remains in the Closing state\n // and can be subject of deposit fraud challenges.\n /// @dev Requirements:\n /// - Wallet maximum BTC balance must be greater than the wallet\n /// minimum BTC balance,\n /// - Wallet maximum BTC transfer must be greater than zero,\n /// - Wallet closing period must be greater than zero.\n function updateWalletParameters(\n uint32 walletCreationPeriod,\n uint64 walletCreationMinBtcBalance,\n uint64 walletCreationMaxBtcBalance,\n uint64 walletClosureMinBtcBalance,\n uint32 walletMaxAge,\n uint64 walletMaxBtcTransfer,\n uint32 walletClosingPeriod\n ) external onlyGovernance {\n self.updateWalletParameters(\n walletCreationPeriod,\n walletCreationMinBtcBalance,\n walletCreationMaxBtcBalance,\n walletClosureMinBtcBalance,\n walletMaxAge,\n walletMaxBtcTransfer,\n walletClosingPeriod\n );\n }\n\n /// @notice Updates parameters related to frauds.\n /// @param fraudChallengeDepositAmount New value of the fraud challenge\n /// deposit amount in wei, it is the amount of ETH the party\n /// challenging the wallet for fraud needs to deposit.\n /// @param fraudChallengeDefeatTimeout New value of the challenge defeat\n /// timeout in seconds, it is the amount of time the wallet has to\n /// defeat a fraud challenge. The value must be greater than zero.\n /// @param fraudSlashingAmount New value of the fraud slashing amount in T,\n /// it is the amount slashed from each wallet member for committing\n /// a fraud.\n /// @param fraudNotifierRewardMultiplier New value of the fraud notifier\n /// reward multiplier as percentage, it determines the percentage of\n /// the notifier reward from the staking contact the notifier of\n /// a fraud receives. The value must be in the range [0, 100].\n /// @dev Requirements:\n /// - Fraud challenge defeat timeout must be greater than 0,\n /// - Fraud notifier reward multiplier must be in the range [0, 100].\n function updateFraudParameters(\n uint96 fraudChallengeDepositAmount,\n uint32 fraudChallengeDefeatTimeout,\n uint96 fraudSlashingAmount,\n uint32 fraudNotifierRewardMultiplier\n ) external onlyGovernance {\n self.updateFraudParameters(\n fraudChallengeDepositAmount,\n fraudChallengeDefeatTimeout,\n fraudSlashingAmount,\n fraudNotifierRewardMultiplier\n );\n }\n\n /// @notice Updates treasury address. The treasury receives the system fees.\n /// @param treasury New value of the treasury address.\n /// @dev The treasury address must not be 0x0.\n // slither-disable-next-line shadowing-local\n function updateTreasury(address treasury) external onlyGovernance {\n self.updateTreasury(treasury);\n }\n\n /// @notice Collection of all revealed deposits indexed by\n /// keccak256(fundingTxHash | fundingOutputIndex).\n /// The fundingTxHash is bytes32 (ordered as in Bitcoin internally)\n /// and fundingOutputIndex an uint32. This mapping may contain valid\n /// and invalid deposits and the wallet is responsible for\n /// validating them before attempting to execute a sweep.\n function deposits(uint256 depositKey)\n external\n view\n returns (Deposit.DepositRequest memory)\n {\n return self.deposits[depositKey];\n }\n\n /// @notice Collection of all pending redemption requests indexed by\n /// redemption key built as\n /// `keccak256(keccak256(redeemerOutputScript) | walletPubKeyHash)`.\n /// The walletPubKeyHash is the 20-byte wallet's public key hash\n /// (computed using Bitcoin HASH160 over the compressed ECDSA\n /// public key) and `redeemerOutputScript` is a Bitcoin script\n /// (P2PKH, P2WPKH, P2SH or P2WSH) that will be used to lock\n /// redeemed BTC as requested by the redeemer. Requests are added\n /// to this mapping by the `requestRedemption` method (duplicates\n /// not allowed) and are removed by one of the following methods:\n /// - `submitRedemptionProof` in case the request was handled\n /// successfully,\n /// - `notifyRedemptionTimeout` in case the request was reported\n /// to be timed out.\n function pendingRedemptions(uint256 redemptionKey)\n external\n view\n returns (Redemption.RedemptionRequest memory)\n {\n return self.pendingRedemptions[redemptionKey];\n }\n\n /// @notice Collection of all timed out redemptions requests indexed by\n /// redemption key built as\n /// `keccak256(keccak256(redeemerOutputScript) | walletPubKeyHash)`.\n /// The walletPubKeyHash is the 20-byte wallet's public key hash\n /// (computed using Bitcoin HASH160 over the compressed ECDSA\n /// public key) and `redeemerOutputScript` is the Bitcoin script\n /// (P2PKH, P2WPKH, P2SH or P2WSH) that is involved in the timed\n /// out request.\n /// Only one method can add to this mapping:\n /// - `notifyRedemptionTimeout` which puts the redemption key\n /// to this mapping based on a timed out request stored\n /// previously in `pendingRedemptions` mapping.\n /// Only one method can remove entries from this mapping:\n /// - `submitRedemptionProof` in case the timed out redemption\n /// request was a part of the proven transaction.\n function timedOutRedemptions(uint256 redemptionKey)\n external\n view\n returns (Redemption.RedemptionRequest memory)\n {\n return self.timedOutRedemptions[redemptionKey];\n }\n\n /// @notice Collection of main UTXOs that are honestly spent indexed by\n /// keccak256(fundingTxHash | fundingOutputIndex). The fundingTxHash\n /// is bytes32 (ordered as in Bitcoin internally) and\n /// fundingOutputIndex an uint32. A main UTXO is considered honestly\n /// spent if it was used as an input of a transaction that have been\n /// proven in the Bridge.\n function spentMainUTXOs(uint256 utxoKey) external view returns (bool) {\n return self.spentMainUTXOs[utxoKey];\n }\n\n /// @notice Gets details about a registered wallet.\n /// @param walletPubKeyHash The 20-byte wallet public key hash (computed\n /// using Bitcoin HASH160 over the compressed ECDSA public key).\n /// @return Wallet details.\n function wallets(bytes20 walletPubKeyHash)\n external\n view\n returns (Wallets.Wallet memory)\n {\n return self.registeredWallets[walletPubKeyHash];\n }\n\n /// @notice Gets the public key hash of the active wallet.\n /// @return The 20-byte public key hash (computed using Bitcoin HASH160\n /// over the compressed ECDSA public key) of the active wallet.\n /// Returns bytes20(0) if there is no active wallet at the moment.\n function activeWalletPubKeyHash() external view returns (bytes20) {\n return self.activeWalletPubKeyHash;\n }\n\n /// @notice Gets the live wallets count.\n /// @return The current count of wallets being in the Live state.\n function liveWalletsCount() external view returns (uint32) {\n return self.liveWalletsCount;\n }\n\n /// @notice Returns the fraud challenge identified by the given key built\n /// as keccak256(walletPublicKey|sighash).\n function fraudChallenges(uint256 challengeKey)\n external\n view\n returns (Fraud.FraudChallenge memory)\n {\n return self.fraudChallenges[challengeKey];\n }\n\n /// @notice Collection of all moved funds sweep requests indexed by\n /// `keccak256(movingFundsTxHash | movingFundsOutputIndex)`.\n /// The `movingFundsTxHash` is `bytes32` (ordered as in Bitcoin\n /// internally) and `movingFundsOutputIndex` an `uint32`. Each entry\n /// is actually an UTXO representing the moved funds and is supposed\n /// to be swept with the current main UTXO of the recipient wallet.\n /// @param requestKey Request key built as\n /// `keccak256(movingFundsTxHash | movingFundsOutputIndex)`.\n /// @return Details of the moved funds sweep request.\n function movedFundsSweepRequests(uint256 requestKey)\n external\n view\n returns (MovingFunds.MovedFundsSweepRequest memory)\n {\n return self.movedFundsSweepRequests[requestKey];\n }\n\n /// @notice Indicates if the vault with the given address is trusted or not.\n /// Depositors can route their revealed deposits only to trusted\n /// vaults and have trusted vaults notified about new deposits as\n /// soon as these deposits get swept. Vaults not trusted by the\n /// Bridge can still be used by Bank balance owners on their own\n /// responsibility - anyone can approve their Bank balance to any\n /// address.\n function isVaultTrusted(address vault) external view returns (bool) {\n return self.isVaultTrusted[vault];\n }\n\n /// @notice Returns the current values of Bridge deposit parameters.\n /// @return depositDustThreshold The minimal amount that can be requested\n /// to deposit. Value of this parameter must take into account the\n /// value of `depositTreasuryFeeDivisor` and `depositTxMaxFee`\n /// parameters in order to make requests that can incur the\n /// treasury and transaction fee and still satisfy the depositor.\n /// @return depositTreasuryFeeDivisor Divisor used to compute the treasury\n /// fee taken from each deposit and transferred to the treasury upon\n /// sweep proof submission. That fee is computed as follows:\n /// `treasuryFee = depositedAmount / depositTreasuryFeeDivisor`\n /// For example, if the treasury fee needs to be 2% of each deposit,\n /// the `depositTreasuryFeeDivisor` should be set to `50`\n /// because `1/50 = 0.02 = 2%`.\n /// @return depositTxMaxFee Maximum amount of BTC transaction fee that can\n /// be incurred by each swept deposit being part of the given sweep\n /// transaction. If the maximum BTC transaction fee is exceeded,\n /// such transaction is considered a fraud.\n /// @return depositRevealAheadPeriod Defines the length of the period that\n /// must be preserved between the deposit reveal time and the\n /// deposit refund locktime. For example, if the deposit become\n /// refundable on August 1st, and the ahead period is 7 days, the\n /// latest moment for deposit reveal is July 25th. Value in seconds.\n function depositParameters()\n external\n view\n returns (\n uint64 depositDustThreshold,\n uint64 depositTreasuryFeeDivisor,\n uint64 depositTxMaxFee,\n uint32 depositRevealAheadPeriod\n )\n {\n depositDustThreshold = self.depositDustThreshold;\n depositTreasuryFeeDivisor = self.depositTreasuryFeeDivisor;\n depositTxMaxFee = self.depositTxMaxFee;\n depositRevealAheadPeriod = self.depositRevealAheadPeriod;\n }\n\n /// @notice Returns the current values of Bridge redemption parameters.\n /// @return redemptionDustThreshold The minimal amount that can be requested\n /// for redemption. Value of this parameter must take into account\n /// the value of `redemptionTreasuryFeeDivisor` and `redemptionTxMaxFee`\n /// parameters in order to make requests that can incur the\n /// treasury and transaction fee and still satisfy the redeemer.\n /// @return redemptionTreasuryFeeDivisor Divisor used to compute the treasury\n /// fee taken from each redemption request and transferred to the\n /// treasury upon successful request finalization. That fee is\n /// computed as follows:\n /// `treasuryFee = requestedAmount / redemptionTreasuryFeeDivisor`\n /// For example, if the treasury fee needs to be 2% of each\n /// redemption request, the `redemptionTreasuryFeeDivisor` should\n /// be set to `50` because `1/50 = 0.02 = 2%`.\n /// @return redemptionTxMaxFee Maximum amount of BTC transaction fee that\n /// can be incurred by each redemption request being part of the\n /// given redemption transaction. If the maximum BTC transaction\n /// fee is exceeded, such transaction is considered a fraud.\n /// This is a per-redemption output max fee for the redemption\n /// transaction.\n /// @return redemptionTxMaxTotalFee Maximum amount of the total BTC\n /// transaction fee that is acceptable in a single redemption\n /// transaction. This is a _total_ max fee for the entire redemption\n /// transaction.\n /// @return redemptionTimeout Time after which the redemption request can be\n /// reported as timed out. It is counted from the moment when the\n /// redemption request was created via `requestRedemption` call.\n /// Reported timed out requests are cancelled and locked balance is\n /// returned to the redeemer in full amount.\n /// @return redemptionTimeoutSlashingAmount The amount of stake slashed\n /// from each member of a wallet for a redemption timeout.\n /// @return redemptionTimeoutNotifierRewardMultiplier The percentage of the\n /// notifier reward from the staking contract the notifier of a\n /// redemption timeout receives. The value is in the range [0, 100].\n function redemptionParameters()\n external\n view\n returns (\n uint64 redemptionDustThreshold,\n uint64 redemptionTreasuryFeeDivisor,\n uint64 redemptionTxMaxFee,\n uint64 redemptionTxMaxTotalFee,\n uint32 redemptionTimeout,\n uint96 redemptionTimeoutSlashingAmount,\n uint32 redemptionTimeoutNotifierRewardMultiplier\n )\n {\n redemptionDustThreshold = self.redemptionDustThreshold;\n redemptionTreasuryFeeDivisor = self.redemptionTreasuryFeeDivisor;\n redemptionTxMaxFee = self.redemptionTxMaxFee;\n redemptionTxMaxTotalFee = self.redemptionTxMaxTotalFee;\n redemptionTimeout = self.redemptionTimeout;\n redemptionTimeoutSlashingAmount = self.redemptionTimeoutSlashingAmount;\n redemptionTimeoutNotifierRewardMultiplier = self\n .redemptionTimeoutNotifierRewardMultiplier;\n }\n\n /// @notice Returns the current values of Bridge moving funds between\n /// wallets parameters.\n /// @return movingFundsTxMaxTotalFee Maximum amount of the total BTC\n /// transaction fee that is acceptable in a single moving funds\n /// transaction. This is a _total_ max fee for the entire moving\n /// funds transaction.\n /// @return movingFundsDustThreshold The minimal satoshi amount that makes\n /// sense to be transferred during the moving funds process. Moving\n /// funds wallets having their BTC balance below that value can\n /// begin closing immediately as transferring such a low value may\n /// not be possible due to BTC network fees.\n /// @return movingFundsTimeoutResetDelay Time after which the moving funds\n /// timeout can be reset in case the target wallet commitment\n /// cannot be submitted due to a lack of live wallets in the system.\n /// It is counted from the moment when the wallet was requested to\n /// move their funds and switched to the MovingFunds state or from\n /// the moment the timeout was reset the last time. Value in seconds\n /// This value should be lower than the value of the\n /// `movingFundsTimeout`.\n /// @return movingFundsTimeout Time after which the moving funds process\n /// can be reported as timed out. It is counted from the moment\n /// when the wallet was requested to move their funds and switched\n /// to the MovingFunds state. Value in seconds.\n /// @return movingFundsTimeoutSlashingAmount The amount of stake slashed\n /// from each member of a wallet for a moving funds timeout.\n /// @return movingFundsTimeoutNotifierRewardMultiplier The percentage of the\n /// notifier reward from the staking contract the notifier of a\n /// moving funds timeout receives. The value is in the range [0, 100].\n /// @return movingFundsCommitmentGasOffset The gas offset used for the\n /// moving funds target wallet commitment transaction cost\n /// reimbursement.\n /// @return movedFundsSweepTxMaxTotalFee Maximum amount of the total BTC\n /// transaction fee that is acceptable in a single moved funds\n /// sweep transaction. This is a _total_ max fee for the entire\n /// moved funds sweep transaction.\n /// @return movedFundsSweepTimeout Time after which the moved funds sweep\n /// process can be reported as timed out. It is counted from the\n /// moment when the wallet was requested to sweep the received funds.\n /// Value in seconds.\n /// @return movedFundsSweepTimeoutSlashingAmount The amount of stake slashed\n /// from each member of a wallet for a moved funds sweep timeout.\n /// @return movedFundsSweepTimeoutNotifierRewardMultiplier The percentage\n /// of the notifier reward from the staking contract the notifier\n /// of a moved funds sweep timeout receives. The value is in the\n /// range [0, 100].\n function movingFundsParameters()\n external\n view\n returns (\n uint64 movingFundsTxMaxTotalFee,\n uint64 movingFundsDustThreshold,\n uint32 movingFundsTimeoutResetDelay,\n uint32 movingFundsTimeout,\n uint96 movingFundsTimeoutSlashingAmount,\n uint32 movingFundsTimeoutNotifierRewardMultiplier,\n uint16 movingFundsCommitmentGasOffset,\n uint64 movedFundsSweepTxMaxTotalFee,\n uint32 movedFundsSweepTimeout,\n uint96 movedFundsSweepTimeoutSlashingAmount,\n uint32 movedFundsSweepTimeoutNotifierRewardMultiplier\n )\n {\n movingFundsTxMaxTotalFee = self.movingFundsTxMaxTotalFee;\n movingFundsDustThreshold = self.movingFundsDustThreshold;\n movingFundsTimeoutResetDelay = self.movingFundsTimeoutResetDelay;\n movingFundsTimeout = self.movingFundsTimeout;\n movingFundsTimeoutSlashingAmount = self\n .movingFundsTimeoutSlashingAmount;\n movingFundsTimeoutNotifierRewardMultiplier = self\n .movingFundsTimeoutNotifierRewardMultiplier;\n movingFundsCommitmentGasOffset = self.movingFundsCommitmentGasOffset;\n movedFundsSweepTxMaxTotalFee = self.movedFundsSweepTxMaxTotalFee;\n movedFundsSweepTimeout = self.movedFundsSweepTimeout;\n movedFundsSweepTimeoutSlashingAmount = self\n .movedFundsSweepTimeoutSlashingAmount;\n movedFundsSweepTimeoutNotifierRewardMultiplier = self\n .movedFundsSweepTimeoutNotifierRewardMultiplier;\n }\n\n /// @return walletCreationPeriod Determines how frequently a new wallet\n /// creation can be requested. Value in seconds.\n /// @return walletCreationMinBtcBalance The minimum BTC threshold in satoshi\n /// that is used to decide about wallet creation.\n /// @return walletCreationMaxBtcBalance The maximum BTC threshold in satoshi\n /// that is used to decide about wallet creation.\n /// @return walletClosureMinBtcBalance The minimum BTC threshold in satoshi\n /// that is used to decide about wallet closure.\n /// @return walletMaxAge The maximum age of a wallet in seconds, after which\n /// the wallet moving funds process can be requested.\n /// @return walletMaxBtcTransfer The maximum BTC amount in satoshi than\n /// can be transferred to a single target wallet during the moving\n /// funds process.\n /// @return walletClosingPeriod Determines the length of the wallet closing\n /// period, i.e. the period when the wallet remains in the Closing\n /// state and can be subject of deposit fraud challenges. Value\n /// in seconds.\n function walletParameters()\n external\n view\n returns (\n uint32 walletCreationPeriod,\n uint64 walletCreationMinBtcBalance,\n uint64 walletCreationMaxBtcBalance,\n uint64 walletClosureMinBtcBalance,\n uint32 walletMaxAge,\n uint64 walletMaxBtcTransfer,\n uint32 walletClosingPeriod\n )\n {\n walletCreationPeriod = self.walletCreationPeriod;\n walletCreationMinBtcBalance = self.walletCreationMinBtcBalance;\n walletCreationMaxBtcBalance = self.walletCreationMaxBtcBalance;\n walletClosureMinBtcBalance = self.walletClosureMinBtcBalance;\n walletMaxAge = self.walletMaxAge;\n walletMaxBtcTransfer = self.walletMaxBtcTransfer;\n walletClosingPeriod = self.walletClosingPeriod;\n }\n\n /// @notice Returns the current values of Bridge fraud parameters.\n /// @return fraudChallengeDepositAmount The amount of ETH in wei the party\n /// challenging the wallet for fraud needs to deposit.\n /// @return fraudChallengeDefeatTimeout The amount of time the wallet has to\n /// defeat a fraud challenge.\n /// @return fraudSlashingAmount The amount slashed from each wallet member\n /// for committing a fraud.\n /// @return fraudNotifierRewardMultiplier The percentage of the notifier\n /// reward from the staking contract the notifier of a fraud\n /// receives. The value is in the range [0, 100].\n function fraudParameters()\n external\n view\n returns (\n uint96 fraudChallengeDepositAmount,\n uint32 fraudChallengeDefeatTimeout,\n uint96 fraudSlashingAmount,\n uint32 fraudNotifierRewardMultiplier\n )\n {\n fraudChallengeDepositAmount = self.fraudChallengeDepositAmount;\n fraudChallengeDefeatTimeout = self.fraudChallengeDefeatTimeout;\n fraudSlashingAmount = self.fraudSlashingAmount;\n fraudNotifierRewardMultiplier = self.fraudNotifierRewardMultiplier;\n }\n\n /// @notice Returns the addresses of contracts Bridge is interacting with.\n /// @return bank Address of the Bank the Bridge belongs to.\n /// @return relay Address of the Bitcoin relay providing the current Bitcoin\n /// network difficulty.\n /// @return ecdsaWalletRegistry Address of the ECDSA Wallet Registry.\n /// @return reimbursementPool Address of the Reimbursement Pool.\n function contractReferences()\n external\n view\n returns (\n Bank bank,\n IRelay relay,\n EcdsaWalletRegistry ecdsaWalletRegistry,\n ReimbursementPool reimbursementPool\n )\n {\n bank = self.bank;\n relay = self.relay;\n ecdsaWalletRegistry = self.ecdsaWalletRegistry;\n reimbursementPool = self.reimbursementPool;\n }\n\n /// @notice Address where the deposit treasury fees will be sent to.\n /// Treasury takes part in the operators rewarding process.\n function treasury() external view returns (address) {\n return self.treasury;\n }\n\n /// @notice The number of confirmations on the Bitcoin chain required to\n /// successfully evaluate an SPV proof.\n function txProofDifficultyFactor() external view returns (uint256) {\n return self.txProofDifficultyFactor;\n }\n}\n" + }, + "contracts/bridge/BridgeGovernanceParameters.sol": { + "content": "// SPDX-License-Identifier: GPL-3.0-only\n\n// ██████████████ ▐████▌ ██████████████\n// ██████████████ ▐████▌ ██████████████\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ██████████████ ▐████▌ ██████████████\n// ██████████████ ▐████▌ ██████████████\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n\npragma solidity 0.8.17;\n\n/// @title Bridge Governance library for storing updatable parameters.\nlibrary BridgeGovernanceParameters {\n struct TreasuryData {\n address newTreasury;\n uint256 treasuryChangeInitiated;\n }\n\n struct DepositData {\n uint64 newDepositDustThreshold;\n uint256 depositDustThresholdChangeInitiated;\n uint64 newDepositTreasuryFeeDivisor;\n uint256 depositTreasuryFeeDivisorChangeInitiated;\n uint64 newDepositTxMaxFee;\n uint256 depositTxMaxFeeChangeInitiated;\n uint32 newDepositRevealAheadPeriod;\n uint256 depositRevealAheadPeriodChangeInitiated;\n }\n\n struct RedemptionData {\n uint64 newRedemptionDustThreshold;\n uint256 redemptionDustThresholdChangeInitiated;\n uint64 newRedemptionTreasuryFeeDivisor;\n uint256 redemptionTreasuryFeeDivisorChangeInitiated;\n uint64 newRedemptionTxMaxFee;\n uint256 redemptionTxMaxFeeChangeInitiated;\n uint64 newRedemptionTxMaxTotalFee;\n uint256 redemptionTxMaxTotalFeeChangeInitiated;\n uint32 newRedemptionTimeout;\n uint256 redemptionTimeoutChangeInitiated;\n uint96 newRedemptionTimeoutSlashingAmount;\n uint256 redemptionTimeoutSlashingAmountChangeInitiated;\n uint32 newRedemptionTimeoutNotifierRewardMultiplier;\n uint256 redemptionTimeoutNotifierRewardMultiplierChangeInitiated;\n }\n\n struct MovingFundsData {\n uint64 newMovingFundsTxMaxTotalFee;\n uint256 movingFundsTxMaxTotalFeeChangeInitiated;\n uint64 newMovingFundsDustThreshold;\n uint256 movingFundsDustThresholdChangeInitiated;\n uint32 newMovingFundsTimeoutResetDelay;\n uint256 movingFundsTimeoutResetDelayChangeInitiated;\n uint32 newMovingFundsTimeout;\n uint256 movingFundsTimeoutChangeInitiated;\n uint96 newMovingFundsTimeoutSlashingAmount;\n uint256 movingFundsTimeoutSlashingAmountChangeInitiated;\n uint32 newMovingFundsTimeoutNotifierRewardMultiplier;\n uint256 movingFundsTimeoutNotifierRewardMultiplierChangeInitiated;\n uint16 newMovingFundsCommitmentGasOffset;\n uint256 movingFundsCommitmentGasOffsetChangeInitiated;\n uint64 newMovedFundsSweepTxMaxTotalFee;\n uint256 movedFundsSweepTxMaxTotalFeeChangeInitiated;\n uint32 newMovedFundsSweepTimeout;\n uint256 movedFundsSweepTimeoutChangeInitiated;\n uint96 newMovedFundsSweepTimeoutSlashingAmount;\n uint256 movedFundsSweepTimeoutSlashingAmountChangeInitiated;\n uint32 newMovedFundsSweepTimeoutNotifierRewardMultiplier;\n uint256 movedFundsSweepTimeoutNotifierRewardMultiplierChangeInitiated;\n }\n\n struct WalletData {\n uint32 newWalletCreationPeriod;\n uint256 walletCreationPeriodChangeInitiated;\n uint64 newWalletCreationMinBtcBalance;\n uint256 walletCreationMinBtcBalanceChangeInitiated;\n uint64 newWalletCreationMaxBtcBalance;\n uint256 walletCreationMaxBtcBalanceChangeInitiated;\n uint64 newWalletClosureMinBtcBalance;\n uint256 walletClosureMinBtcBalanceChangeInitiated;\n uint32 newWalletMaxAge;\n uint256 walletMaxAgeChangeInitiated;\n uint64 newWalletMaxBtcTransfer;\n uint256 walletMaxBtcTransferChangeInitiated;\n uint32 newWalletClosingPeriod;\n uint256 walletClosingPeriodChangeInitiated;\n }\n\n struct FraudData {\n uint96 newFraudChallengeDepositAmount;\n uint256 fraudChallengeDepositAmountChangeInitiated;\n uint32 newFraudChallengeDefeatTimeout;\n uint256 fraudChallengeDefeatTimeoutChangeInitiated;\n uint96 newFraudSlashingAmount;\n uint256 fraudSlashingAmountChangeInitiated;\n uint32 newFraudNotifierRewardMultiplier;\n uint256 fraudNotifierRewardMultiplierChangeInitiated;\n }\n\n event DepositDustThresholdUpdateStarted(\n uint64 newDepositDustThreshold,\n uint256 timestamp\n );\n event DepositDustThresholdUpdated(uint64 depositDustThreshold);\n\n event DepositTreasuryFeeDivisorUpdateStarted(\n uint64 depositTreasuryFeeDivisor,\n uint256 timestamp\n );\n event DepositTreasuryFeeDivisorUpdated(uint64 depositTreasuryFeeDivisor);\n\n event DepositTxMaxFeeUpdateStarted(\n uint64 newDepositTxMaxFee,\n uint256 timestamp\n );\n event DepositTxMaxFeeUpdated(uint64 depositTxMaxFee);\n\n event DepositRevealAheadPeriodUpdateStarted(\n uint32 newDepositRevealAheadPeriod,\n uint256 timestamp\n );\n event DepositRevealAheadPeriodUpdated(uint32 depositRevealAheadPeriod);\n\n event RedemptionDustThresholdUpdateStarted(\n uint64 newRedemptionDustThreshold,\n uint256 timestamp\n );\n event RedemptionDustThresholdUpdated(uint64 redemptionDustThreshold);\n\n event RedemptionTreasuryFeeDivisorUpdateStarted(\n uint64 newRedemptionTreasuryFeeDivisor,\n uint256 timestamp\n );\n event RedemptionTreasuryFeeDivisorUpdated(\n uint64 redemptionTreasuryFeeDivisor\n );\n\n event RedemptionTxMaxFeeUpdateStarted(\n uint64 newRedemptionTxMaxFee,\n uint256 timestamp\n );\n event RedemptionTxMaxFeeUpdated(uint64 redemptionTxMaxFee);\n\n event RedemptionTxMaxTotalFeeUpdateStarted(\n uint64 newRedemptionTxMaxTotalFee,\n uint256 timestamp\n );\n event RedemptionTxMaxTotalFeeUpdated(uint64 redemptionTxMaxTotalFee);\n\n event RedemptionTimeoutUpdateStarted(\n uint32 newRedemptionTimeout,\n uint256 timestamp\n );\n event RedemptionTimeoutUpdated(uint32 redemptionTimeout);\n\n event RedemptionTimeoutSlashingAmountUpdateStarted(\n uint96 newRedemptionTimeoutSlashingAmount,\n uint256 timestamp\n );\n event RedemptionTimeoutSlashingAmountUpdated(\n uint96 redemptionTimeoutSlashingAmount\n );\n\n event RedemptionTimeoutNotifierRewardMultiplierUpdateStarted(\n uint32 newRedemptionTimeoutNotifierRewardMultiplier,\n uint256 timestamp\n );\n event RedemptionTimeoutNotifierRewardMultiplierUpdated(\n uint32 redemptionTimeoutNotifierRewardMultiplier\n );\n\n event MovingFundsTxMaxTotalFeeUpdateStarted(\n uint64 newMovingFundsTxMaxTotalFee,\n uint256 timestamp\n );\n event MovingFundsTxMaxTotalFeeUpdated(uint64 movingFundsTxMaxTotalFee);\n\n event MovingFundsDustThresholdUpdateStarted(\n uint64 newMovingFundsDustThreshold,\n uint256 timestamp\n );\n event MovingFundsDustThresholdUpdated(uint64 movingFundsDustThreshold);\n\n event MovingFundsTimeoutResetDelayUpdateStarted(\n uint32 newMovingFundsTimeoutResetDelay,\n uint256 timestamp\n );\n event MovingFundsTimeoutResetDelayUpdated(\n uint32 movingFundsTimeoutResetDelay\n );\n\n event MovingFundsTimeoutUpdateStarted(\n uint32 newMovingFundsTimeout,\n uint256 timestamp\n );\n event MovingFundsTimeoutUpdated(uint32 movingFundsTimeout);\n\n event MovingFundsTimeoutSlashingAmountUpdateStarted(\n uint96 newMovingFundsTimeoutSlashingAmount,\n uint256 timestamp\n );\n event MovingFundsTimeoutSlashingAmountUpdated(\n uint96 movingFundsTimeoutSlashingAmount\n );\n\n event MovingFundsTimeoutNotifierRewardMultiplierUpdateStarted(\n uint32 newMovingFundsTimeoutNotifierRewardMultiplier,\n uint256 timestamp\n );\n event MovingFundsTimeoutNotifierRewardMultiplierUpdated(\n uint32 movingFundsTimeoutNotifierRewardMultiplier\n );\n\n event MovingFundsCommitmentGasOffsetUpdateStarted(\n uint16 newMovingFundsCommitmentGasOffset,\n uint256 timestamp\n );\n event MovingFundsCommitmentGasOffsetUpdated(\n uint16 movingFundsCommitmentGasOffset\n );\n\n event MovedFundsSweepTxMaxTotalFeeUpdateStarted(\n uint64 newMovedFundsSweepTxMaxTotalFee,\n uint256 timestamp\n );\n event MovedFundsSweepTxMaxTotalFeeUpdated(\n uint64 movedFundsSweepTxMaxTotalFee\n );\n\n event MovedFundsSweepTimeoutUpdateStarted(\n uint32 newMovedFundsSweepTimeout,\n uint256 timestamp\n );\n event MovedFundsSweepTimeoutUpdated(uint32 movedFundsSweepTimeout);\n\n event MovedFundsSweepTimeoutSlashingAmountUpdateStarted(\n uint96 newMovedFundsSweepTimeoutSlashingAmount,\n uint256 timestamp\n );\n event MovedFundsSweepTimeoutSlashingAmountUpdated(\n uint96 movedFundsSweepTimeoutSlashingAmount\n );\n\n event MovedFundsSweepTimeoutNotifierRewardMultiplierUpdateStarted(\n uint32 newMovedFundsSweepTimeoutNotifierRewardMultiplier,\n uint256 timestamp\n );\n event MovedFundsSweepTimeoutNotifierRewardMultiplierUpdated(\n uint32 movedFundsSweepTimeoutNotifierRewardMultiplier\n );\n\n event WalletCreationPeriodUpdateStarted(\n uint32 newWalletCreationPeriod,\n uint256 timestamp\n );\n event WalletCreationPeriodUpdated(uint32 walletCreationPeriod);\n\n event WalletCreationMinBtcBalanceUpdateStarted(\n uint64 newWalletCreationMinBtcBalance,\n uint256 timestamp\n );\n event WalletCreationMinBtcBalanceUpdated(\n uint64 walletCreationMinBtcBalance\n );\n\n event WalletCreationMaxBtcBalanceUpdateStarted(\n uint64 newWalletCreationMaxBtcBalance,\n uint256 timestamp\n );\n event WalletCreationMaxBtcBalanceUpdated(\n uint64 walletCreationMaxBtcBalance\n );\n\n event WalletClosureMinBtcBalanceUpdateStarted(\n uint64 newWalletClosureMinBtcBalance,\n uint256 timestamp\n );\n event WalletClosureMinBtcBalanceUpdated(uint64 walletClosureMinBtcBalance);\n\n event WalletMaxAgeUpdateStarted(uint32 newWalletMaxAge, uint256 timestamp);\n event WalletMaxAgeUpdated(uint32 walletMaxAge);\n\n event WalletMaxBtcTransferUpdateStarted(\n uint64 newWalletMaxBtcTransfer,\n uint256 timestamp\n );\n event WalletMaxBtcTransferUpdated(uint64 walletMaxBtcTransfer);\n\n event WalletClosingPeriodUpdateStarted(\n uint32 newWalletClosingPeriod,\n uint256 timestamp\n );\n event WalletClosingPeriodUpdated(uint32 walletClosingPeriod);\n\n event FraudChallengeDepositAmountUpdateStarted(\n uint96 newFraudChallengeDepositAmount,\n uint256 timestamp\n );\n event FraudChallengeDepositAmountUpdated(\n uint96 fraudChallengeDepositAmount\n );\n\n event FraudChallengeDefeatTimeoutUpdateStarted(\n uint32 newFraudChallengeDefeatTimeout,\n uint256 timestamp\n );\n event FraudChallengeDefeatTimeoutUpdated(\n uint32 fraudChallengeDefeatTimeout\n );\n\n event FraudSlashingAmountUpdateStarted(\n uint96 newFraudSlashingAmount,\n uint256 timestamp\n );\n event FraudSlashingAmountUpdated(uint96 fraudSlashingAmount);\n\n event FraudNotifierRewardMultiplierUpdateStarted(\n uint32 newFraudNotifierRewardMultiplier,\n uint256 timestamp\n );\n event FraudNotifierRewardMultiplierUpdated(\n uint32 fraudNotifierRewardMultiplier\n );\n\n event TreasuryUpdateStarted(address newTreasury, uint256 timestamp);\n event TreasuryUpdated(address treasury);\n\n /// @notice Reverts if called before the governance delay elapses.\n /// @param changeInitiatedTimestamp Timestamp indicating the beginning\n /// of the change.\n modifier onlyAfterGovernanceDelay(\n uint256 changeInitiatedTimestamp,\n uint256 governanceDelay\n ) {\n /* solhint-disable not-rely-on-time */\n require(changeInitiatedTimestamp > 0, \"Change not initiated\");\n require(\n block.timestamp - changeInitiatedTimestamp >= governanceDelay,\n \"Governance delay has not elapsed\"\n );\n _;\n /* solhint-enable not-rely-on-time */\n }\n\n // --- Deposit\n\n /// @notice Begins the deposit dust threshold amount update process.\n /// @param _newDepositDustThreshold New deposit dust threshold amount.\n function beginDepositDustThresholdUpdate(\n DepositData storage self,\n uint64 _newDepositDustThreshold\n ) external {\n /* solhint-disable not-rely-on-time */\n self.newDepositDustThreshold = _newDepositDustThreshold;\n self.depositDustThresholdChangeInitiated = block.timestamp;\n emit DepositDustThresholdUpdateStarted(\n _newDepositDustThreshold,\n block.timestamp\n );\n /* solhint-enable not-rely-on-time */\n }\n\n /// @notice Finalizes the deposit dust threshold amount update process.\n /// @dev Can be called after the governance delay elapses.\n function finalizeDepositDustThresholdUpdate(\n DepositData storage self,\n uint256 governanceDelay\n )\n external\n onlyAfterGovernanceDelay(\n self.depositDustThresholdChangeInitiated,\n governanceDelay\n )\n {\n emit DepositDustThresholdUpdated(self.newDepositDustThreshold);\n\n self.newDepositDustThreshold = 0;\n self.depositDustThresholdChangeInitiated = 0;\n }\n\n /// @notice Begins the deposit treasury fee divisor amount update process.\n /// @param _newDepositTreasuryFeeDivisor New deposit treasury fee divisor amount.\n function beginDepositTreasuryFeeDivisorUpdate(\n DepositData storage self,\n uint64 _newDepositTreasuryFeeDivisor\n ) external {\n /* solhint-disable not-rely-on-time */\n self.newDepositTreasuryFeeDivisor = _newDepositTreasuryFeeDivisor;\n self.depositTreasuryFeeDivisorChangeInitiated = block.timestamp;\n emit DepositTreasuryFeeDivisorUpdateStarted(\n _newDepositTreasuryFeeDivisor,\n block.timestamp\n );\n /* solhint-enable not-rely-on-time */\n }\n\n /// @notice Finalizes the deposit treasury fee divisor amount update process.\n /// @dev Can be called after the governance delay elapses.\n function finalizeDepositTreasuryFeeDivisorUpdate(\n DepositData storage self,\n uint256 governanceDelay\n )\n external\n onlyAfterGovernanceDelay(\n self.depositTreasuryFeeDivisorChangeInitiated,\n governanceDelay\n )\n {\n emit DepositTreasuryFeeDivisorUpdated(\n self.newDepositTreasuryFeeDivisor\n );\n\n self.newDepositTreasuryFeeDivisor = 0;\n self.depositTreasuryFeeDivisorChangeInitiated = 0;\n }\n\n /// @notice Begins the deposit tx max fee amount update process.\n /// @param _newDepositTxMaxFee New deposit tx max fee amount.\n function beginDepositTxMaxFeeUpdate(\n DepositData storage self,\n uint64 _newDepositTxMaxFee\n ) external {\n /* solhint-disable not-rely-on-time */\n self.newDepositTxMaxFee = _newDepositTxMaxFee;\n self.depositTxMaxFeeChangeInitiated = block.timestamp;\n emit DepositTxMaxFeeUpdateStarted(_newDepositTxMaxFee, block.timestamp);\n /* solhint-enable not-rely-on-time */\n }\n\n /// @notice Finalizes the deposit tx max fee amount update process.\n /// @dev Can be called after the governance delay elapses.\n function finalizeDepositTxMaxFeeUpdate(\n DepositData storage self,\n uint256 governanceDelay\n )\n external\n onlyAfterGovernanceDelay(\n self.depositTxMaxFeeChangeInitiated,\n governanceDelay\n )\n {\n emit DepositTxMaxFeeUpdated(self.newDepositTxMaxFee);\n\n self.newDepositTxMaxFee = 0;\n self.depositTxMaxFeeChangeInitiated = 0;\n }\n\n /// @notice Begins the deposit reveal ahead period update process.\n /// @param _newDepositRevealAheadPeriod New deposit reveal ahead period.\n function beginDepositRevealAheadPeriodUpdate(\n DepositData storage self,\n uint32 _newDepositRevealAheadPeriod\n ) external {\n /* solhint-disable not-rely-on-time */\n self.newDepositRevealAheadPeriod = _newDepositRevealAheadPeriod;\n self.depositRevealAheadPeriodChangeInitiated = block.timestamp;\n emit DepositRevealAheadPeriodUpdateStarted(\n _newDepositRevealAheadPeriod,\n block.timestamp\n );\n /* solhint-enable not-rely-on-time */\n }\n\n /// @notice Finalizes the deposit reveal ahead period update process.\n /// @dev Can be called after the governance delay elapses.\n function finalizeDepositRevealAheadPeriodUpdate(\n DepositData storage self,\n uint256 governanceDelay\n )\n external\n onlyAfterGovernanceDelay(\n self.depositRevealAheadPeriodChangeInitiated,\n governanceDelay\n )\n {\n emit DepositRevealAheadPeriodUpdated(self.newDepositRevealAheadPeriod);\n\n self.newDepositRevealAheadPeriod = 0;\n self.depositRevealAheadPeriodChangeInitiated = 0;\n }\n\n // --- Redemption\n\n /// @notice Begins the redemption dust threshold amount update process.\n /// @param _newRedemptionDustThreshold New redemption dust threshold amount.\n function beginRedemptionDustThresholdUpdate(\n RedemptionData storage self,\n uint64 _newRedemptionDustThreshold\n ) external {\n /* solhint-disable not-rely-on-time */\n self.newRedemptionDustThreshold = _newRedemptionDustThreshold;\n self.redemptionDustThresholdChangeInitiated = block.timestamp;\n emit RedemptionDustThresholdUpdateStarted(\n _newRedemptionDustThreshold,\n block.timestamp\n );\n /* solhint-enable not-rely-on-time */\n }\n\n /// @notice Finalizes the redemption dust threshold amount update process.\n /// @dev Can be called after the governance delay elapses.\n function finalizeRedemptionDustThresholdUpdate(\n RedemptionData storage self,\n uint256 governanceDelay\n )\n external\n onlyAfterGovernanceDelay(\n self.redemptionDustThresholdChangeInitiated,\n governanceDelay\n )\n {\n emit RedemptionDustThresholdUpdated(self.newRedemptionDustThreshold);\n\n self.newRedemptionDustThreshold = 0;\n self.redemptionDustThresholdChangeInitiated = 0;\n }\n\n /// @notice Begins the redemption treasury fee divisor amount update process.\n /// @param _newRedemptionTreasuryFeeDivisor New redemption treasury fee divisor\n /// amount.\n function beginRedemptionTreasuryFeeDivisorUpdate(\n RedemptionData storage self,\n uint64 _newRedemptionTreasuryFeeDivisor\n ) external {\n /* solhint-disable not-rely-on-time */\n self.newRedemptionTreasuryFeeDivisor = _newRedemptionTreasuryFeeDivisor;\n self.redemptionTreasuryFeeDivisorChangeInitiated = block.timestamp;\n emit RedemptionTreasuryFeeDivisorUpdateStarted(\n _newRedemptionTreasuryFeeDivisor,\n block.timestamp\n );\n /* solhint-enable not-rely-on-time */\n }\n\n /// @notice Finalizes the redemption treasury fee divisor amount update process.\n /// @dev Can be called after the governance delay elapses.\n function finalizeRedemptionTreasuryFeeDivisorUpdate(\n RedemptionData storage self,\n uint256 governanceDelay\n )\n external\n onlyAfterGovernanceDelay(\n self.redemptionTreasuryFeeDivisorChangeInitiated,\n governanceDelay\n )\n {\n emit RedemptionTreasuryFeeDivisorUpdated(\n self.newRedemptionTreasuryFeeDivisor\n );\n\n self.newRedemptionTreasuryFeeDivisor = 0;\n self.redemptionTreasuryFeeDivisorChangeInitiated = 0;\n }\n\n /// @notice Begins the redemption tx max fee amount update process.\n /// @param _newRedemptionTxMaxFee New redemption tx max fee amount.\n function beginRedemptionTxMaxFeeUpdate(\n RedemptionData storage self,\n uint64 _newRedemptionTxMaxFee\n ) external {\n /* solhint-disable not-rely-on-time */\n self.newRedemptionTxMaxFee = _newRedemptionTxMaxFee;\n self.redemptionTxMaxFeeChangeInitiated = block.timestamp;\n emit RedemptionTxMaxFeeUpdateStarted(\n _newRedemptionTxMaxFee,\n block.timestamp\n );\n /* solhint-enable not-rely-on-time */\n }\n\n /// @notice Finalizes the redemption tx max fee amount update process.\n /// @dev Can be called after the governance delay elapses.\n function finalizeRedemptionTxMaxFeeUpdate(\n RedemptionData storage self,\n uint256 governanceDelay\n )\n external\n onlyAfterGovernanceDelay(\n self.redemptionTxMaxFeeChangeInitiated,\n governanceDelay\n )\n {\n emit RedemptionTxMaxFeeUpdated(self.newRedemptionTxMaxFee);\n\n self.newRedemptionTxMaxFee = 0;\n self.redemptionTxMaxFeeChangeInitiated = 0;\n }\n\n /// @notice Begins the redemption tx max total fee amount update process.\n /// @param _newRedemptionTxMaxTotalFee New redemption tx max total fee amount.\n function beginRedemptionTxMaxTotalFeeUpdate(\n RedemptionData storage self,\n uint64 _newRedemptionTxMaxTotalFee\n ) external {\n /* solhint-disable not-rely-on-time */\n self.newRedemptionTxMaxTotalFee = _newRedemptionTxMaxTotalFee;\n self.redemptionTxMaxTotalFeeChangeInitiated = block.timestamp;\n emit RedemptionTxMaxTotalFeeUpdateStarted(\n _newRedemptionTxMaxTotalFee,\n block.timestamp\n );\n /* solhint-enable not-rely-on-time */\n }\n\n /// @notice Finalizes the redemption tx max total fee amount update process.\n /// @dev Can be called after the governance delay elapses.\n function finalizeRedemptionTxMaxTotalFeeUpdate(\n RedemptionData storage self,\n uint256 governanceDelay\n )\n external\n onlyAfterGovernanceDelay(\n self.redemptionTxMaxTotalFeeChangeInitiated,\n governanceDelay\n )\n {\n emit RedemptionTxMaxTotalFeeUpdated(self.newRedemptionTxMaxTotalFee);\n\n self.newRedemptionTxMaxTotalFee = 0;\n self.redemptionTxMaxTotalFeeChangeInitiated = 0;\n }\n\n /// @notice Begins the redemption timeout amount update process.\n /// @param _newRedemptionTimeout New redemption timeout amount.\n function beginRedemptionTimeoutUpdate(\n RedemptionData storage self,\n uint32 _newRedemptionTimeout\n ) external {\n /* solhint-disable not-rely-on-time */\n self.newRedemptionTimeout = _newRedemptionTimeout;\n self.redemptionTimeoutChangeInitiated = block.timestamp;\n emit RedemptionTimeoutUpdateStarted(\n _newRedemptionTimeout,\n block.timestamp\n );\n /* solhint-enable not-rely-on-time */\n }\n\n /// @notice Finalizes the redemption timeout amount update\n /// process.\n /// @dev Can be called after the governance delay elapses.\n function finalizeRedemptionTimeoutUpdate(\n RedemptionData storage self,\n uint256 governanceDelay\n )\n external\n onlyAfterGovernanceDelay(\n self.redemptionTimeoutChangeInitiated,\n governanceDelay\n )\n {\n emit RedemptionTimeoutUpdated(self.newRedemptionTimeout);\n\n self.newRedemptionTimeout = 0;\n self.redemptionTimeoutChangeInitiated = 0;\n }\n\n /// @notice Begins the redemption timeout slashing amount update process.\n /// @param _newRedemptionTimeoutSlashingAmount New redemption timeout slashing\n /// amount.\n function beginRedemptionTimeoutSlashingAmountUpdate(\n RedemptionData storage self,\n uint96 _newRedemptionTimeoutSlashingAmount\n ) external {\n /* solhint-disable not-rely-on-time */\n self\n .newRedemptionTimeoutSlashingAmount = _newRedemptionTimeoutSlashingAmount;\n self.redemptionTimeoutSlashingAmountChangeInitiated = block.timestamp;\n emit RedemptionTimeoutSlashingAmountUpdateStarted(\n _newRedemptionTimeoutSlashingAmount,\n block.timestamp\n );\n /* solhint-enable not-rely-on-time */\n }\n\n /// @notice Finalizes the redemption timeout slashing amount update process.\n /// @dev Can be called after the governance delay elapses.\n function finalizeRedemptionTimeoutSlashingAmountUpdate(\n RedemptionData storage self,\n uint256 governanceDelay\n )\n external\n onlyAfterGovernanceDelay(\n self.redemptionTimeoutSlashingAmountChangeInitiated,\n governanceDelay\n )\n {\n emit RedemptionTimeoutSlashingAmountUpdated(\n self.newRedemptionTimeoutSlashingAmount\n );\n\n self.newRedemptionTimeoutSlashingAmount = 0;\n self.redemptionTimeoutSlashingAmountChangeInitiated = 0;\n }\n\n /// @notice Begins the redemption timeout notifier reward multiplier amount\n /// update process.\n /// @param _newRedemptionTimeoutNotifierRewardMultiplier New redemption\n /// timeout notifier reward multiplier amount.\n function beginRedemptionTimeoutNotifierRewardMultiplierUpdate(\n RedemptionData storage self,\n uint32 _newRedemptionTimeoutNotifierRewardMultiplier\n ) external {\n /* solhint-disable not-rely-on-time */\n self\n .newRedemptionTimeoutNotifierRewardMultiplier = _newRedemptionTimeoutNotifierRewardMultiplier;\n self.redemptionTimeoutNotifierRewardMultiplierChangeInitiated = block\n .timestamp;\n emit RedemptionTimeoutNotifierRewardMultiplierUpdateStarted(\n _newRedemptionTimeoutNotifierRewardMultiplier,\n block.timestamp\n );\n /* solhint-enable not-rely-on-time */\n }\n\n /// @notice Finalizes the redemption timeout notifier reward multiplier amount update process.\n /// @dev Can be called after the governance delay elapses.\n function finalizeRedemptionTimeoutNotifierRewardMultiplierUpdate(\n RedemptionData storage self,\n uint256 governanceDelay\n )\n external\n onlyAfterGovernanceDelay(\n self.redemptionTimeoutNotifierRewardMultiplierChangeInitiated,\n governanceDelay\n )\n {\n emit RedemptionTimeoutNotifierRewardMultiplierUpdated(\n self.newRedemptionTimeoutNotifierRewardMultiplier\n );\n\n self.newRedemptionTimeoutNotifierRewardMultiplier = 0;\n self.redemptionTimeoutNotifierRewardMultiplierChangeInitiated = 0;\n }\n\n // --- Moving funds\n\n /// @notice Begins the moving funds tx max total fee amount update process.\n /// @param _newMovingFundsTxMaxTotalFee New moving funds tx max total fee amount.\n function beginMovingFundsTxMaxTotalFeeUpdate(\n MovingFundsData storage self,\n uint64 _newMovingFundsTxMaxTotalFee\n ) external {\n /* solhint-disable not-rely-on-time */\n self.newMovingFundsTxMaxTotalFee = _newMovingFundsTxMaxTotalFee;\n self.movingFundsTxMaxTotalFeeChangeInitiated = block.timestamp;\n emit MovingFundsTxMaxTotalFeeUpdateStarted(\n _newMovingFundsTxMaxTotalFee,\n block.timestamp\n );\n /* solhint-enable not-rely-on-time */\n }\n\n /// @notice Finalizes the moving funds tx max total fee amount update process.\n /// @dev Can be called after the governance delay elapses.\n function finalizeMovingFundsTxMaxTotalFeeUpdate(\n MovingFundsData storage self,\n uint256 governanceDelay\n )\n external\n onlyAfterGovernanceDelay(\n self.movingFundsTxMaxTotalFeeChangeInitiated,\n governanceDelay\n )\n {\n emit MovingFundsTxMaxTotalFeeUpdated(self.newMovingFundsTxMaxTotalFee);\n\n self.newMovingFundsTxMaxTotalFee = 0;\n self.movingFundsTxMaxTotalFeeChangeInitiated = 0;\n }\n\n /// @notice Begins the moving funds dust threshold amount update process.\n /// @param _newMovingFundsDustThreshold New moving funds dust threshold amount.\n function beginMovingFundsDustThresholdUpdate(\n MovingFundsData storage self,\n uint64 _newMovingFundsDustThreshold\n ) external {\n /* solhint-disable not-rely-on-time */\n self.newMovingFundsDustThreshold = _newMovingFundsDustThreshold;\n self.movingFundsDustThresholdChangeInitiated = block.timestamp;\n emit MovingFundsDustThresholdUpdateStarted(\n _newMovingFundsDustThreshold,\n block.timestamp\n );\n /* solhint-enable not-rely-on-time */\n }\n\n /// @notice Finalizes the moving funds dust threshold amount update process.\n /// @dev Can be called after the governance delay elapses.\n function finalizeMovingFundsDustThresholdUpdate(\n MovingFundsData storage self,\n uint256 governanceDelay\n )\n external\n onlyAfterGovernanceDelay(\n self.movingFundsDustThresholdChangeInitiated,\n governanceDelay\n )\n {\n emit MovingFundsDustThresholdUpdated(self.newMovingFundsDustThreshold);\n\n self.newMovingFundsDustThreshold = 0;\n self.movingFundsDustThresholdChangeInitiated = 0;\n }\n\n /// @notice Begins the moving funds timeout reset delay amount update process.\n /// @param _newMovingFundsTimeoutResetDelay New moving funds timeout reset\n /// delay amount.\n function beginMovingFundsTimeoutResetDelayUpdate(\n MovingFundsData storage self,\n uint32 _newMovingFundsTimeoutResetDelay\n ) external {\n /* solhint-disable not-rely-on-time */\n self.newMovingFundsTimeoutResetDelay = _newMovingFundsTimeoutResetDelay;\n self.movingFundsTimeoutResetDelayChangeInitiated = block.timestamp;\n emit MovingFundsTimeoutResetDelayUpdateStarted(\n _newMovingFundsTimeoutResetDelay,\n block.timestamp\n );\n /* solhint-enable not-rely-on-time */\n }\n\n /// @notice Finalizes the moving funds timeout reset delay amount update process.\n /// @dev Can be called after the governance delay elapses.\n function finalizeMovingFundsTimeoutResetDelayUpdate(\n MovingFundsData storage self,\n uint256 governanceDelay\n )\n external\n onlyAfterGovernanceDelay(\n self.movingFundsTimeoutResetDelayChangeInitiated,\n governanceDelay\n )\n {\n emit MovingFundsTimeoutResetDelayUpdated(\n self.newMovingFundsTimeoutResetDelay\n );\n\n self.newMovingFundsTimeoutResetDelay = 0;\n self.movingFundsTimeoutResetDelayChangeInitiated = 0;\n }\n\n /// @notice Begins the moving funds timeout amount update process.\n /// @param _newMovingFundsTimeout New moving funds timeout amount.\n function beginMovingFundsTimeoutUpdate(\n MovingFundsData storage self,\n uint32 _newMovingFundsTimeout\n ) external {\n /* solhint-disable not-rely-on-time */\n self.newMovingFundsTimeout = _newMovingFundsTimeout;\n self.movingFundsTimeoutChangeInitiated = block.timestamp;\n emit MovingFundsTimeoutUpdateStarted(\n _newMovingFundsTimeout,\n block.timestamp\n );\n /* solhint-enable not-rely-on-time */\n }\n\n /// @notice Finalizes the moving funds timeout amount update process.\n /// @dev Can be called after the governance delay elapses.\n function finalizeMovingFundsTimeoutUpdate(\n MovingFundsData storage self,\n uint256 governanceDelay\n )\n external\n onlyAfterGovernanceDelay(\n self.movingFundsTimeoutChangeInitiated,\n governanceDelay\n )\n {\n emit MovingFundsTimeoutUpdated(self.newMovingFundsTimeout);\n\n self.newMovingFundsTimeout = 0;\n self.movingFundsTimeoutChangeInitiated = 0;\n }\n\n /// @notice Begins the moving funds timeout slashing amount update process.\n /// @param _newMovingFundsTimeoutSlashingAmount New moving funds timeout slashing amount.\n function beginMovingFundsTimeoutSlashingAmountUpdate(\n MovingFundsData storage self,\n uint96 _newMovingFundsTimeoutSlashingAmount\n ) external {\n /* solhint-disable not-rely-on-time */\n self\n .newMovingFundsTimeoutSlashingAmount = _newMovingFundsTimeoutSlashingAmount;\n self.movingFundsTimeoutSlashingAmountChangeInitiated = block.timestamp;\n emit MovingFundsTimeoutSlashingAmountUpdateStarted(\n _newMovingFundsTimeoutSlashingAmount,\n block.timestamp\n );\n /* solhint-enable not-rely-on-time */\n }\n\n /// @notice Finalizes the moving funds timeout slashing amount update process.\n /// @dev Can be called after the governance delay elapses.\n function finalizeMovingFundsTimeoutSlashingAmountUpdate(\n MovingFundsData storage self,\n uint256 governanceDelay\n )\n external\n onlyAfterGovernanceDelay(\n self.movingFundsTimeoutSlashingAmountChangeInitiated,\n governanceDelay\n )\n {\n emit MovingFundsTimeoutSlashingAmountUpdated(\n self.newMovingFundsTimeoutSlashingAmount\n );\n\n self.newMovingFundsTimeoutSlashingAmount = 0;\n self.movingFundsTimeoutSlashingAmountChangeInitiated = 0;\n }\n\n /// @notice Begins the moving funds timeout notifier reward multiplier amount\n /// update process.\n /// @param _newMovingFundsTimeoutNotifierRewardMultiplier New moving funds\n /// timeout notifier reward multiplier amount.\n function beginMovingFundsTimeoutNotifierRewardMultiplierUpdate(\n MovingFundsData storage self,\n uint32 _newMovingFundsTimeoutNotifierRewardMultiplier\n ) external {\n /* solhint-disable not-rely-on-time */\n self\n .newMovingFundsTimeoutNotifierRewardMultiplier = _newMovingFundsTimeoutNotifierRewardMultiplier;\n self.movingFundsTimeoutNotifierRewardMultiplierChangeInitiated = block\n .timestamp;\n emit MovingFundsTimeoutNotifierRewardMultiplierUpdateStarted(\n _newMovingFundsTimeoutNotifierRewardMultiplier,\n block.timestamp\n );\n /* solhint-enable not-rely-on-time */\n }\n\n /// @notice Finalizes the moving funds timeout notifier reward multiplier\n /// amount update process.\n /// @dev Can be called after the governance delay elapses.\n function finalizeMovingFundsTimeoutNotifierRewardMultiplierUpdate(\n MovingFundsData storage self,\n uint256 governanceDelay\n )\n external\n onlyAfterGovernanceDelay(\n self.movingFundsTimeoutNotifierRewardMultiplierChangeInitiated,\n governanceDelay\n )\n {\n emit MovingFundsTimeoutNotifierRewardMultiplierUpdated(\n self.newMovingFundsTimeoutNotifierRewardMultiplier\n );\n\n self.newMovingFundsTimeoutNotifierRewardMultiplier = 0;\n self.movingFundsTimeoutNotifierRewardMultiplierChangeInitiated = 0;\n }\n\n /// @notice Begins the moving funds commitment gas offset update process.\n /// @param _newMovingFundsCommitmentGasOffset New moving funds commitment\n /// gas offset.\n function beginMovingFundsCommitmentGasOffsetUpdate(\n MovingFundsData storage self,\n uint16 _newMovingFundsCommitmentGasOffset\n ) external {\n /* solhint-disable not-rely-on-time */\n self\n .newMovingFundsCommitmentGasOffset = _newMovingFundsCommitmentGasOffset;\n self.movingFundsCommitmentGasOffsetChangeInitiated = block.timestamp;\n emit MovingFundsCommitmentGasOffsetUpdateStarted(\n _newMovingFundsCommitmentGasOffset,\n block.timestamp\n );\n /* solhint-enable not-rely-on-time */\n }\n\n /// @notice Finalizes the moving funds commitment gas offset update process.\n /// @dev Can be called after the governance delay elapses.\n function finalizeMovingFundsCommitmentGasOffsetUpdate(\n MovingFundsData storage self,\n uint256 governanceDelay\n )\n external\n onlyAfterGovernanceDelay(\n self.movingFundsCommitmentGasOffsetChangeInitiated,\n governanceDelay\n )\n {\n emit MovingFundsCommitmentGasOffsetUpdated(\n self.newMovingFundsCommitmentGasOffset\n );\n\n self.newMovingFundsCommitmentGasOffset = 0;\n self.movingFundsCommitmentGasOffsetChangeInitiated = 0;\n }\n\n /// @notice Begins the moved funds sweep tx max total fee amount update process.\n /// @param _newMovedFundsSweepTxMaxTotalFee New moved funds sweep tx max total\n /// fee amount.\n function beginMovedFundsSweepTxMaxTotalFeeUpdate(\n MovingFundsData storage self,\n uint64 _newMovedFundsSweepTxMaxTotalFee\n ) external {\n /* solhint-disable not-rely-on-time */\n self.newMovedFundsSweepTxMaxTotalFee = _newMovedFundsSweepTxMaxTotalFee;\n self.movedFundsSweepTxMaxTotalFeeChangeInitiated = block.timestamp;\n emit MovedFundsSweepTxMaxTotalFeeUpdateStarted(\n _newMovedFundsSweepTxMaxTotalFee,\n block.timestamp\n );\n /* solhint-enable not-rely-on-time */\n }\n\n /// @notice Finalizes the moved funds sweep tx max total fee amount update\n /// process.\n /// @dev Can be called after the governance delay elapses.\n function finalizeMovedFundsSweepTxMaxTotalFeeUpdate(\n MovingFundsData storage self,\n uint256 governanceDelay\n )\n external\n onlyAfterGovernanceDelay(\n self.movedFundsSweepTxMaxTotalFeeChangeInitiated,\n governanceDelay\n )\n {\n emit MovedFundsSweepTxMaxTotalFeeUpdated(\n self.newMovedFundsSweepTxMaxTotalFee\n );\n\n self.newMovedFundsSweepTxMaxTotalFee = 0;\n self.movedFundsSweepTxMaxTotalFeeChangeInitiated = 0;\n }\n\n /// @notice Begins the moved funds sweep timeout amount update process.\n /// @param _newMovedFundsSweepTimeout New moved funds sweep timeout amount.\n function beginMovedFundsSweepTimeoutUpdate(\n MovingFundsData storage self,\n uint32 _newMovedFundsSweepTimeout\n ) external {\n /* solhint-disable not-rely-on-time */\n self.newMovedFundsSweepTimeout = _newMovedFundsSweepTimeout;\n self.movedFundsSweepTimeoutChangeInitiated = block.timestamp;\n emit MovedFundsSweepTimeoutUpdateStarted(\n _newMovedFundsSweepTimeout,\n block.timestamp\n );\n /* solhint-enable not-rely-on-time */\n }\n\n /// @notice Finalizes the moved funds sweep timeout amount update process.\n /// @dev Can be called after the governance delay elapses.\n function finalizeMovedFundsSweepTimeoutUpdate(\n MovingFundsData storage self,\n uint256 governanceDelay\n )\n external\n onlyAfterGovernanceDelay(\n self.movedFundsSweepTimeoutChangeInitiated,\n governanceDelay\n )\n {\n emit MovedFundsSweepTimeoutUpdated(self.newMovedFundsSweepTimeout);\n\n self.newMovedFundsSweepTimeout = 0;\n self.movedFundsSweepTimeoutChangeInitiated = 0;\n }\n\n /// @notice Begins the moved funds sweep timeout slashing amount update\n /// process.\n /// @param _newMovedFundsSweepTimeoutSlashingAmount New moved funds sweep\n /// timeout slashing amount.\n function beginMovedFundsSweepTimeoutSlashingAmountUpdate(\n MovingFundsData storage self,\n uint96 _newMovedFundsSweepTimeoutSlashingAmount\n ) external {\n /* solhint-disable not-rely-on-time */\n self\n .newMovedFundsSweepTimeoutSlashingAmount = _newMovedFundsSweepTimeoutSlashingAmount;\n self.movedFundsSweepTimeoutSlashingAmountChangeInitiated = block\n .timestamp;\n emit MovedFundsSweepTimeoutSlashingAmountUpdateStarted(\n _newMovedFundsSweepTimeoutSlashingAmount,\n block.timestamp\n );\n /* solhint-enable not-rely-on-time */\n }\n\n /// @notice Finalizes the moved funds sweep timeout slashing amount\n /// update process.\n /// @dev Can be called after the governance delay elapses.\n function finalizeMovedFundsSweepTimeoutSlashingAmountUpdate(\n MovingFundsData storage self,\n uint256 governanceDelay\n )\n external\n onlyAfterGovernanceDelay(\n self.movedFundsSweepTimeoutSlashingAmountChangeInitiated,\n governanceDelay\n )\n {\n emit MovedFundsSweepTimeoutSlashingAmountUpdated(\n self.newMovedFundsSweepTimeoutSlashingAmount\n );\n\n self.newMovedFundsSweepTimeoutSlashingAmount = 0;\n self.movedFundsSweepTimeoutSlashingAmountChangeInitiated = 0;\n }\n\n /// @notice Begins the moved funds sweep timeout notifier reward multiplier\n /// amount update process.\n /// @param _newMovedFundsSweepTimeoutNotifierRewardMultiplier New moved funds\n /// sweep timeout notifier reward multiplier amount.\n function beginMovedFundsSweepTimeoutNotifierRewardMultiplierUpdate(\n MovingFundsData storage self,\n uint32 _newMovedFundsSweepTimeoutNotifierRewardMultiplier\n ) external {\n /* solhint-disable not-rely-on-time */\n self\n .newMovedFundsSweepTimeoutNotifierRewardMultiplier = _newMovedFundsSweepTimeoutNotifierRewardMultiplier;\n self\n .movedFundsSweepTimeoutNotifierRewardMultiplierChangeInitiated = block\n .timestamp;\n emit MovedFundsSweepTimeoutNotifierRewardMultiplierUpdateStarted(\n _newMovedFundsSweepTimeoutNotifierRewardMultiplier,\n block.timestamp\n );\n /* solhint-enable not-rely-on-time */\n }\n\n /// @notice Finalizes the moved funds sweep timeout notifier reward multiplier\n /// amount update process.\n /// @dev Can be called after the governance delay elapses.\n function finalizeMovedFundsSweepTimeoutNotifierRewardMultiplierUpdate(\n MovingFundsData storage self,\n uint256 governanceDelay\n )\n external\n onlyAfterGovernanceDelay(\n self.movedFundsSweepTimeoutNotifierRewardMultiplierChangeInitiated,\n governanceDelay\n )\n {\n emit MovedFundsSweepTimeoutNotifierRewardMultiplierUpdated(\n self.newMovedFundsSweepTimeoutNotifierRewardMultiplier\n );\n\n self.newMovedFundsSweepTimeoutNotifierRewardMultiplier = 0;\n self.movedFundsSweepTimeoutNotifierRewardMultiplierChangeInitiated = 0;\n }\n\n // --- Wallet params\n\n /// @notice Begins the wallet creation period amount update process.\n /// @param _newWalletCreationPeriod New wallet creation period amount.\n function beginWalletCreationPeriodUpdate(\n WalletData storage self,\n uint32 _newWalletCreationPeriod\n ) external {\n /* solhint-disable not-rely-on-time */\n self.newWalletCreationPeriod = _newWalletCreationPeriod;\n self.walletCreationPeriodChangeInitiated = block.timestamp;\n emit WalletCreationPeriodUpdateStarted(\n _newWalletCreationPeriod,\n block.timestamp\n );\n /* solhint-enable not-rely-on-time */\n }\n\n /// @notice Finalizes the wallet creation period amount update process.\n /// @dev Can be called after the governance delay elapses.\n function finalizeWalletCreationPeriodUpdate(\n WalletData storage self,\n uint256 governanceDelay\n )\n external\n onlyAfterGovernanceDelay(\n self.walletCreationPeriodChangeInitiated,\n governanceDelay\n )\n {\n emit WalletCreationPeriodUpdated(self.newWalletCreationPeriod);\n\n self.newWalletCreationPeriod = 0;\n self.walletCreationPeriodChangeInitiated = 0;\n }\n\n /// @notice Begins the wallet creation min btc balance amount update process.\n /// @param _newWalletCreationMinBtcBalance New wallet creation min btc balance\n /// amount.\n function beginWalletCreationMinBtcBalanceUpdate(\n WalletData storage self,\n uint64 _newWalletCreationMinBtcBalance\n ) external {\n /* solhint-disable not-rely-on-time */\n self.newWalletCreationMinBtcBalance = _newWalletCreationMinBtcBalance;\n self.walletCreationMinBtcBalanceChangeInitiated = block.timestamp;\n emit WalletCreationMinBtcBalanceUpdateStarted(\n _newWalletCreationMinBtcBalance,\n block.timestamp\n );\n /* solhint-enable not-rely-on-time */\n }\n\n /// @notice Finalizes the wallet creation min btc balance amount update process.\n /// @dev Can be called after the governance delay elapses.\n function finalizeWalletCreationMinBtcBalanceUpdate(\n WalletData storage self,\n uint256 governanceDelay\n )\n external\n onlyAfterGovernanceDelay(\n self.walletCreationMinBtcBalanceChangeInitiated,\n governanceDelay\n )\n {\n emit WalletCreationMinBtcBalanceUpdated(\n self.newWalletCreationMinBtcBalance\n );\n\n self.newWalletCreationMinBtcBalance = 0;\n self.walletCreationMinBtcBalanceChangeInitiated = 0;\n }\n\n /// @notice Begins the wallet creation max btc balance amount update process.\n /// @param _newWalletCreationMaxBtcBalance New wallet creation max btc balance\n /// amount.\n function beginWalletCreationMaxBtcBalanceUpdate(\n WalletData storage self,\n uint64 _newWalletCreationMaxBtcBalance\n ) external {\n /* solhint-disable not-rely-on-time */\n self.newWalletCreationMaxBtcBalance = _newWalletCreationMaxBtcBalance;\n self.walletCreationMaxBtcBalanceChangeInitiated = block.timestamp;\n emit WalletCreationMaxBtcBalanceUpdateStarted(\n _newWalletCreationMaxBtcBalance,\n block.timestamp\n );\n /* solhint-enable not-rely-on-time */\n }\n\n /// @notice Finalizes the wallet creation max btc balance amount update process.\n /// @dev Can be called after the governance delay elapses.\n function finalizeWalletCreationMaxBtcBalanceUpdate(\n WalletData storage self,\n uint256 governanceDelay\n )\n external\n onlyAfterGovernanceDelay(\n self.walletCreationMaxBtcBalanceChangeInitiated,\n governanceDelay\n )\n {\n emit WalletCreationMaxBtcBalanceUpdated(\n self.newWalletCreationMaxBtcBalance\n );\n\n self.newWalletCreationMaxBtcBalance = 0;\n self.walletCreationMaxBtcBalanceChangeInitiated = 0;\n }\n\n /// @notice Begins the wallet closure min btc balance amount update process.\n /// @param _newWalletClosureMinBtcBalance New wallet closure min btc balance amount.\n function beginWalletClosureMinBtcBalanceUpdate(\n WalletData storage self,\n uint64 _newWalletClosureMinBtcBalance\n ) external {\n /* solhint-disable not-rely-on-time */\n self.newWalletClosureMinBtcBalance = _newWalletClosureMinBtcBalance;\n self.walletClosureMinBtcBalanceChangeInitiated = block.timestamp;\n emit WalletClosureMinBtcBalanceUpdateStarted(\n _newWalletClosureMinBtcBalance,\n block.timestamp\n );\n /* solhint-enable not-rely-on-time */\n }\n\n /// @notice Finalizes the wallet closure min btc balance amount update process.\n /// @dev Can be called after the governance delay elapses.\n function finalizeWalletClosureMinBtcBalanceUpdate(\n WalletData storage self,\n uint256 governanceDelay\n )\n external\n onlyAfterGovernanceDelay(\n self.walletClosureMinBtcBalanceChangeInitiated,\n governanceDelay\n )\n {\n emit WalletClosureMinBtcBalanceUpdated(\n self.newWalletClosureMinBtcBalance\n );\n\n self.newWalletClosureMinBtcBalance = 0;\n self.walletClosureMinBtcBalanceChangeInitiated = 0;\n }\n\n /// @notice Begins the wallet max age amount update process.\n /// @param _newWalletMaxAge New wallet max age amount.\n function beginWalletMaxAgeUpdate(\n WalletData storage self,\n uint32 _newWalletMaxAge\n ) external {\n /* solhint-disable not-rely-on-time */\n self.newWalletMaxAge = _newWalletMaxAge;\n self.walletMaxAgeChangeInitiated = block.timestamp;\n emit WalletMaxAgeUpdateStarted(_newWalletMaxAge, block.timestamp);\n /* solhint-enable not-rely-on-time */\n }\n\n /// @notice Finalizes the wallet max age amount update process.\n /// @dev Can be called after the governance delay elapses.\n function finalizeWalletMaxAgeUpdate(\n WalletData storage self,\n uint256 governanceDelay\n )\n external\n onlyAfterGovernanceDelay(\n self.walletMaxAgeChangeInitiated,\n governanceDelay\n )\n {\n emit WalletMaxAgeUpdated(self.newWalletMaxAge);\n\n self.newWalletMaxAge = 0;\n self.walletMaxAgeChangeInitiated = 0;\n }\n\n /// @notice Begins the wallet max btc transfer amount update process.\n /// @param _newWalletMaxBtcTransfer New wallet max btc transfer amount.\n function beginWalletMaxBtcTransferUpdate(\n WalletData storage self,\n uint64 _newWalletMaxBtcTransfer\n ) external {\n /* solhint-disable not-rely-on-time */\n self.newWalletMaxBtcTransfer = _newWalletMaxBtcTransfer;\n self.walletMaxBtcTransferChangeInitiated = block.timestamp;\n emit WalletMaxBtcTransferUpdateStarted(\n _newWalletMaxBtcTransfer,\n block.timestamp\n );\n /* solhint-enable not-rely-on-time */\n }\n\n /// @notice Finalizes the wallet max btc transfer amount update process.\n /// @dev Can be called after the governance delay elapses.\n function finalizeWalletMaxBtcTransferUpdate(\n WalletData storage self,\n uint256 governanceDelay\n )\n external\n onlyAfterGovernanceDelay(\n self.walletMaxBtcTransferChangeInitiated,\n governanceDelay\n )\n {\n emit WalletMaxBtcTransferUpdated(self.newWalletMaxBtcTransfer);\n\n self.newWalletMaxBtcTransfer = 0;\n self.walletMaxBtcTransferChangeInitiated = 0;\n }\n\n /// @notice Begins the wallet closing period amount update process.\n /// @param _newWalletClosingPeriod New wallet closing period amount.\n function beginWalletClosingPeriodUpdate(\n WalletData storage self,\n uint32 _newWalletClosingPeriod\n ) external {\n /* solhint-disable not-rely-on-time */\n self.newWalletClosingPeriod = _newWalletClosingPeriod;\n self.walletClosingPeriodChangeInitiated = block.timestamp;\n emit WalletClosingPeriodUpdateStarted(\n _newWalletClosingPeriod,\n block.timestamp\n );\n /* solhint-enable not-rely-on-time */\n }\n\n /// @notice Finalizes the wallet closing period amount update process.\n /// @dev Can be called after the governance delay elapses.\n function finalizeWalletClosingPeriodUpdate(\n WalletData storage self,\n uint256 governanceDelay\n )\n external\n onlyAfterGovernanceDelay(\n self.walletClosingPeriodChangeInitiated,\n governanceDelay\n )\n {\n emit WalletClosingPeriodUpdated(self.newWalletClosingPeriod);\n\n self.newWalletClosingPeriod = 0;\n self.walletClosingPeriodChangeInitiated = 0;\n }\n\n // --- Fraud\n\n /// @notice Begins the fraud challenge deposit amount update process.\n /// @param _newFraudChallengeDepositAmount New fraud challenge deposit amount.\n function beginFraudChallengeDepositAmountUpdate(\n FraudData storage self,\n uint96 _newFraudChallengeDepositAmount\n ) external {\n /* solhint-disable not-rely-on-time */\n self.newFraudChallengeDepositAmount = _newFraudChallengeDepositAmount;\n self.fraudChallengeDepositAmountChangeInitiated = block.timestamp;\n emit FraudChallengeDepositAmountUpdateStarted(\n _newFraudChallengeDepositAmount,\n block.timestamp\n );\n /* solhint-enable not-rely-on-time */\n }\n\n /// @notice Finalizes the fraud challenge deposit amount update process.\n /// @dev Can be called after the governance delay elapses.\n function finalizeFraudChallengeDepositAmountUpdate(\n FraudData storage self,\n uint256 governanceDelay\n )\n external\n onlyAfterGovernanceDelay(\n self.fraudChallengeDepositAmountChangeInitiated,\n governanceDelay\n )\n {\n emit FraudChallengeDepositAmountUpdated(\n self.newFraudChallengeDepositAmount\n );\n\n self.newFraudChallengeDepositAmount = 0;\n self.fraudChallengeDepositAmountChangeInitiated = 0;\n }\n\n /// @notice Begins the fraud challenge defeat timeout amount update process.\n /// @param _newFraudChallengeDefeatTimeout New fraud challenge defeat timeout\n /// amount.\n function beginFraudChallengeDefeatTimeoutUpdate(\n FraudData storage self,\n uint32 _newFraudChallengeDefeatTimeout\n ) external {\n /* solhint-disable not-rely-on-time */\n self.newFraudChallengeDefeatTimeout = _newFraudChallengeDefeatTimeout;\n self.fraudChallengeDefeatTimeoutChangeInitiated = block.timestamp;\n emit FraudChallengeDefeatTimeoutUpdateStarted(\n _newFraudChallengeDefeatTimeout,\n block.timestamp\n );\n /* solhint-enable not-rely-on-time */\n }\n\n /// @notice Finalizes the fraud challenge defeat timeout amount update process.\n /// @dev Can be called after the governance delay elapses.\n function finalizeFraudChallengeDefeatTimeoutUpdate(\n FraudData storage self,\n uint256 governanceDelay\n )\n external\n onlyAfterGovernanceDelay(\n self.fraudChallengeDefeatTimeoutChangeInitiated,\n governanceDelay\n )\n {\n emit FraudChallengeDefeatTimeoutUpdated(\n self.newFraudChallengeDefeatTimeout\n );\n\n self.newFraudChallengeDefeatTimeout = 0;\n self.fraudChallengeDefeatTimeoutChangeInitiated = 0;\n }\n\n /// @notice Begins the fraud slashing amount update process.\n /// @param _newFraudSlashingAmount New fraud slashing amount.\n function beginFraudSlashingAmountUpdate(\n FraudData storage self,\n uint96 _newFraudSlashingAmount\n ) external {\n /* solhint-disable not-rely-on-time */\n self.newFraudSlashingAmount = _newFraudSlashingAmount;\n self.fraudSlashingAmountChangeInitiated = block.timestamp;\n emit FraudSlashingAmountUpdateStarted(\n _newFraudSlashingAmount,\n block.timestamp\n );\n /* solhint-enable not-rely-on-time */\n }\n\n /// @notice Finalizes the fraud slashing amount update process.\n /// @dev Can be called after the governance delay elapses.\n function finalizeFraudSlashingAmountUpdate(\n FraudData storage self,\n uint256 governanceDelay\n )\n external\n onlyAfterGovernanceDelay(\n self.fraudSlashingAmountChangeInitiated,\n governanceDelay\n )\n {\n emit FraudSlashingAmountUpdated(self.newFraudSlashingAmount);\n\n self.newFraudSlashingAmount = 0;\n self.fraudSlashingAmountChangeInitiated = 0;\n }\n\n /// @notice Begins the fraud notifier reward multiplier amount update process.\n /// @param _newFraudNotifierRewardMultiplier New fraud notifier reward multiplier\n /// amount.\n function beginFraudNotifierRewardMultiplierUpdate(\n FraudData storage self,\n uint32 _newFraudNotifierRewardMultiplier\n ) external {\n /* solhint-disable not-rely-on-time */\n self\n .newFraudNotifierRewardMultiplier = _newFraudNotifierRewardMultiplier;\n self.fraudNotifierRewardMultiplierChangeInitiated = block.timestamp;\n emit FraudNotifierRewardMultiplierUpdateStarted(\n _newFraudNotifierRewardMultiplier,\n block.timestamp\n );\n /* solhint-enable not-rely-on-time */\n }\n\n /// @notice Finalizes the fraud notifier reward multiplier amount update process.\n /// @dev Can be called after the governance delay elapses.\n function finalizeFraudNotifierRewardMultiplierUpdate(\n FraudData storage self,\n uint256 governanceDelay\n )\n external\n onlyAfterGovernanceDelay(\n self.fraudNotifierRewardMultiplierChangeInitiated,\n governanceDelay\n )\n {\n emit FraudNotifierRewardMultiplierUpdated(\n self.newFraudNotifierRewardMultiplier\n );\n\n self.newFraudNotifierRewardMultiplier = 0;\n self.fraudNotifierRewardMultiplierChangeInitiated = 0;\n }\n\n /// @notice Begins the treasury address update process.\n /// @dev It does not perform any parameter validation.\n /// @param _newTreasury New treasury address.\n function beginTreasuryUpdate(\n TreasuryData storage self,\n address _newTreasury\n ) external {\n /* solhint-disable not-rely-on-time */\n self.newTreasury = _newTreasury;\n self.treasuryChangeInitiated = block.timestamp;\n emit TreasuryUpdateStarted(_newTreasury, block.timestamp);\n /* solhint-enable not-rely-on-time */\n }\n\n /// @notice Finalizes the treasury address update process.\n /// @dev Can be called after the governance delay elapses.\n function finalizeTreasuryUpdate(\n TreasuryData storage self,\n uint256 governanceDelay\n )\n external\n onlyAfterGovernanceDelay(self.treasuryChangeInitiated, governanceDelay)\n {\n emit TreasuryUpdated(self.newTreasury);\n\n self.newTreasury = address(0);\n self.treasuryChangeInitiated = 0;\n }\n}\n" + }, + "contracts/bridge/BridgeState.sol": { + "content": "// SPDX-License-Identifier: GPL-3.0-only\n\n// ██████████████ ▐████▌ ██████████████\n// ██████████████ ▐████▌ ██████████████\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ██████████████ ▐████▌ ██████████████\n// ██████████████ ▐████▌ ██████████████\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n\npragma solidity 0.8.17;\n\nimport {IWalletRegistry as EcdsaWalletRegistry} from \"@keep-network/ecdsa/contracts/api/IWalletRegistry.sol\";\nimport \"@keep-network/random-beacon/contracts/ReimbursementPool.sol\";\n\nimport \"./IRelay.sol\";\nimport \"./Deposit.sol\";\nimport \"./Redemption.sol\";\nimport \"./Fraud.sol\";\nimport \"./Wallets.sol\";\nimport \"./MovingFunds.sol\";\n\nimport \"../bank/Bank.sol\";\n\nlibrary BridgeState {\n struct Storage {\n // Address of the Bank the Bridge belongs to.\n Bank bank;\n // Bitcoin relay providing the current Bitcoin network difficulty.\n IRelay relay;\n // The number of confirmations on the Bitcoin chain required to\n // successfully evaluate an SPV proof.\n uint96 txProofDifficultyFactor;\n // ECDSA Wallet Registry contract handle.\n EcdsaWalletRegistry ecdsaWalletRegistry;\n // Reimbursement Pool contract handle.\n ReimbursementPool reimbursementPool;\n // Address where the deposit and redemption treasury fees will be sent\n // to. Treasury takes part in the operators rewarding process.\n address treasury;\n // Move depositDustThreshold to the next storage slot for a more\n // efficient variable layout in the storage.\n // slither-disable-next-line unused-state\n bytes32 __treasuryAlignmentGap;\n // The minimal amount that can be requested to deposit.\n // Value of this parameter must take into account the value of\n // `depositTreasuryFeeDivisor` and `depositTxMaxFee` parameters in order\n // to make requests that can incur the treasury and transaction fee and\n // still satisfy the depositor.\n uint64 depositDustThreshold;\n // Divisor used to compute the treasury fee taken from each deposit and\n // transferred to the treasury upon sweep proof submission. That fee is\n // computed as follows:\n // `treasuryFee = depositedAmount / depositTreasuryFeeDivisor`\n // For example, if the treasury fee needs to be 2% of each deposit,\n // the `depositTreasuryFeeDivisor` should be set to `50` because\n // `1/50 = 0.02 = 2%`.\n uint64 depositTreasuryFeeDivisor;\n // Maximum amount of BTC transaction fee that can be incurred by each\n // swept deposit being part of the given sweep transaction. If the\n // maximum BTC transaction fee is exceeded, such transaction is\n // considered a fraud.\n //\n // This is a per-deposit input max fee for the sweep transaction.\n uint64 depositTxMaxFee;\n // Defines the length of the period that must be preserved between\n // the deposit reveal time and the deposit refund locktime. For example,\n // if the deposit become refundable on August 1st, and the ahead period\n // is 7 days, the latest moment for deposit reveal is July 25th.\n // Value in seconds. The value equal to zero disables the validation\n // of this parameter.\n uint32 depositRevealAheadPeriod;\n // Move movingFundsTxMaxTotalFee to the next storage slot for a more\n // efficient variable layout in the storage.\n // slither-disable-next-line unused-state\n bytes32 __depositAlignmentGap;\n // Maximum amount of the total BTC transaction fee that is acceptable in\n // a single moving funds transaction.\n //\n // This is a TOTAL max fee for the moving funds transaction. Note\n // that `depositTxMaxFee` is per single deposit and `redemptionTxMaxFee`\n // is per single redemption. `movingFundsTxMaxTotalFee` is a total\n // fee for the entire transaction.\n uint64 movingFundsTxMaxTotalFee;\n // The minimal satoshi amount that makes sense to be transferred during\n // the moving funds process. Moving funds wallets having their BTC\n // balance below that value can begin closing immediately as\n // transferring such a low value may not be possible due to\n // BTC network fees. The value of this parameter must always be lower\n // than `redemptionDustThreshold` in order to prevent redemption requests\n // with values lower or equal to `movingFundsDustThreshold`.\n uint64 movingFundsDustThreshold;\n // Time after which the moving funds timeout can be reset in case the\n // target wallet commitment cannot be submitted due to a lack of live\n // wallets in the system. It is counted from the moment when the wallet\n // was requested to move their funds and switched to the MovingFunds\n // state or from the moment the timeout was reset the last time.\n // Value in seconds. This value should be lower than the value\n // of the `movingFundsTimeout`.\n uint32 movingFundsTimeoutResetDelay;\n // Time after which the moving funds process can be reported as\n // timed out. It is counted from the moment when the wallet\n // was requested to move their funds and switched to the MovingFunds\n // state. Value in seconds.\n uint32 movingFundsTimeout;\n // The amount of stake slashed from each member of a wallet for a moving\n // funds timeout.\n uint96 movingFundsTimeoutSlashingAmount;\n // The percentage of the notifier reward from the staking contract\n // the notifier of a moving funds timeout receives. The value is in the\n // range [0, 100].\n uint32 movingFundsTimeoutNotifierRewardMultiplier;\n // The gas offset used for the target wallet commitment transaction cost\n // reimbursement.\n uint16 movingFundsCommitmentGasOffset;\n // Move movedFundsSweepTxMaxTotalFee to the next storage slot for a more\n // efficient variable layout in the storage.\n // slither-disable-next-line unused-state\n bytes32 __movingFundsAlignmentGap;\n // Maximum amount of the total BTC transaction fee that is acceptable in\n // a single moved funds sweep transaction.\n //\n // This is a TOTAL max fee for the moved funds sweep transaction. Note\n // that `depositTxMaxFee` is per single deposit and `redemptionTxMaxFee`\n // is per single redemption. `movedFundsSweepTxMaxTotalFee` is a total\n // fee for the entire transaction.\n uint64 movedFundsSweepTxMaxTotalFee;\n // Time after which the moved funds sweep process can be reported as\n // timed out. It is counted from the moment when the recipient wallet\n // was requested to sweep the received funds. Value in seconds.\n uint32 movedFundsSweepTimeout;\n // The amount of stake slashed from each member of a wallet for a moved\n // funds sweep timeout.\n uint96 movedFundsSweepTimeoutSlashingAmount;\n // The percentage of the notifier reward from the staking contract\n // the notifier of a moved funds sweep timeout receives. The value is\n // in the range [0, 100].\n uint32 movedFundsSweepTimeoutNotifierRewardMultiplier;\n // The minimal amount that can be requested for redemption.\n // Value of this parameter must take into account the value of\n // `redemptionTreasuryFeeDivisor` and `redemptionTxMaxFee`\n // parameters in order to make requests that can incur the\n // treasury and transaction fee and still satisfy the redeemer.\n // Additionally, the value of this parameter must always be greater\n // than `movingFundsDustThreshold` in order to prevent redemption\n // requests with values lower or equal to `movingFundsDustThreshold`.\n uint64 redemptionDustThreshold;\n // Divisor used to compute the treasury fee taken from each\n // redemption request and transferred to the treasury upon\n // successful request finalization. That fee is computed as follows:\n // `treasuryFee = requestedAmount / redemptionTreasuryFeeDivisor`\n // For example, if the treasury fee needs to be 2% of each\n // redemption request, the `redemptionTreasuryFeeDivisor` should\n // be set to `50` because `1/50 = 0.02 = 2%`.\n uint64 redemptionTreasuryFeeDivisor;\n // Maximum amount of BTC transaction fee that can be incurred by\n // each redemption request being part of the given redemption\n // transaction. If the maximum BTC transaction fee is exceeded, such\n // transaction is considered a fraud.\n //\n // This is a per-redemption output max fee for the redemption\n // transaction.\n uint64 redemptionTxMaxFee;\n // Maximum amount of the total BTC transaction fee that is acceptable in\n // a single redemption transaction.\n //\n // This is a TOTAL max fee for the redemption transaction. Note\n // that the `redemptionTxMaxFee` is per single redemption.\n // `redemptionTxMaxTotalFee` is a total fee for the entire transaction.\n uint64 redemptionTxMaxTotalFee;\n // Move redemptionTimeout to the next storage slot for a more efficient\n // variable layout in the storage.\n // slither-disable-next-line unused-state\n bytes32 __redemptionAlignmentGap;\n // Time after which the redemption request can be reported as\n // timed out. It is counted from the moment when the redemption\n // request was created via `requestRedemption` call. Reported\n // timed out requests are cancelled and locked TBTC is returned\n // to the redeemer in full amount.\n uint32 redemptionTimeout;\n // The amount of stake slashed from each member of a wallet for a\n // redemption timeout.\n uint96 redemptionTimeoutSlashingAmount;\n // The percentage of the notifier reward from the staking contract\n // the notifier of a redemption timeout receives. The value is in the\n // range [0, 100].\n uint32 redemptionTimeoutNotifierRewardMultiplier;\n // The amount of ETH in wei the party challenging the wallet for fraud\n // needs to deposit.\n uint96 fraudChallengeDepositAmount;\n // The amount of time the wallet has to defeat a fraud challenge.\n uint32 fraudChallengeDefeatTimeout;\n // The amount of stake slashed from each member of a wallet for a fraud.\n uint96 fraudSlashingAmount;\n // The percentage of the notifier reward from the staking contract\n // the notifier of a fraud receives. The value is in the range [0, 100].\n uint32 fraudNotifierRewardMultiplier;\n // Determines how frequently a new wallet creation can be requested.\n // Value in seconds.\n uint32 walletCreationPeriod;\n // The minimum BTC threshold in satoshi that is used to decide about\n // wallet creation. Specifically, we allow for the creation of a new\n // wallet if the active wallet is old enough and their amount of BTC\n // is greater than or equal this threshold.\n uint64 walletCreationMinBtcBalance;\n // The maximum BTC threshold in satoshi that is used to decide about\n // wallet creation. Specifically, we allow for the creation of a new\n // wallet if the active wallet's amount of BTC is greater than or equal\n // this threshold, regardless of the active wallet's age.\n uint64 walletCreationMaxBtcBalance;\n // The minimum BTC threshold in satoshi that is used to decide about\n // wallet closing. Specifically, we allow for the closure of the given\n // wallet if their amount of BTC is lesser than this threshold,\n // regardless of the wallet's age.\n uint64 walletClosureMinBtcBalance;\n // The maximum age of a wallet in seconds, after which the wallet\n // moving funds process can be requested.\n uint32 walletMaxAge;\n // 20-byte wallet public key hash being reference to the currently\n // active wallet. Can be unset to the zero value under certain\n // circumstances.\n bytes20 activeWalletPubKeyHash;\n // The current number of wallets in the Live state.\n uint32 liveWalletsCount;\n // The maximum BTC amount in satoshi than can be transferred to a single\n // target wallet during the moving funds process.\n uint64 walletMaxBtcTransfer;\n // Determines the length of the wallet closing period, i.e. the period\n // when the wallet remains in the Closing state and can be subject\n // of deposit fraud challenges. This value is in seconds and should be\n // greater than the deposit refund time plus some time margin.\n uint32 walletClosingPeriod;\n // Collection of all revealed deposits indexed by\n // `keccak256(fundingTxHash | fundingOutputIndex)`.\n // The `fundingTxHash` is `bytes32` (ordered as in Bitcoin internally)\n // and `fundingOutputIndex` an `uint32`. This mapping may contain valid\n // and invalid deposits and the wallet is responsible for validating\n // them before attempting to execute a sweep.\n mapping(uint256 => Deposit.DepositRequest) deposits;\n // Indicates if the vault with the given address is trusted.\n // Depositors can route their revealed deposits only to trusted vaults\n // and have trusted vaults notified about new deposits as soon as these\n // deposits get swept. Vaults not trusted by the Bridge can still be\n // used by Bank balance owners on their own responsibility - anyone can\n // approve their Bank balance to any address.\n mapping(address => bool) isVaultTrusted;\n // Indicates if the address is a trusted SPV maintainer.\n // The SPV proof does not check whether the transaction is a part of the\n // Bitcoin mainnet, it only checks whether the transaction has been\n // mined performing the required amount of work as on Bitcoin mainnet.\n // The possibility of submitting SPV proofs is limited to trusted SPV\n // maintainers. The system expects transaction confirmations with the\n // required work accumulated, so trusted SPV maintainers can not prove\n // the transaction without providing the required Bitcoin proof of work.\n // Trusted maintainers address the issue of an economic game between\n // tBTC and Bitcoin mainnet where large Bitcoin mining pools can decide\n // to use their hash power to mine fake Bitcoin blocks to prove them in\n // tBTC instead of receiving Bitcoin miner rewards.\n mapping(address => bool) isSpvMaintainer;\n // Collection of all moved funds sweep requests indexed by\n // `keccak256(movingFundsTxHash | movingFundsOutputIndex)`.\n // The `movingFundsTxHash` is `bytes32` (ordered as in Bitcoin\n // internally) and `movingFundsOutputIndex` an `uint32`. Each entry\n // is actually an UTXO representing the moved funds and is supposed\n // to be swept with the current main UTXO of the recipient wallet.\n mapping(uint256 => MovingFunds.MovedFundsSweepRequest) movedFundsSweepRequests;\n // Collection of all pending redemption requests indexed by\n // redemption key built as\n // `keccak256(keccak256(redeemerOutputScript) | walletPubKeyHash)`.\n // The `walletPubKeyHash` is the 20-byte wallet's public key hash\n // (computed using Bitcoin HASH160 over the compressed ECDSA\n // public key) and `redeemerOutputScript` is a Bitcoin script\n // (P2PKH, P2WPKH, P2SH or P2WSH) that will be used to lock\n // redeemed BTC as requested by the redeemer. Requests are added\n // to this mapping by the `requestRedemption` method (duplicates\n // not allowed) and are removed by one of the following methods:\n // - `submitRedemptionProof` in case the request was handled\n // successfully,\n // - `notifyRedemptionTimeout` in case the request was reported\n // to be timed out.\n mapping(uint256 => Redemption.RedemptionRequest) pendingRedemptions;\n // Collection of all timed out redemptions requests indexed by\n // redemption key built as\n // `keccak256(keccak256(redeemerOutputScript) | walletPubKeyHash)`.\n // The `walletPubKeyHash` is the 20-byte wallet's public key hash\n // (computed using Bitcoin HASH160 over the compressed ECDSA\n // public key) and `redeemerOutputScript` is the Bitcoin script\n // (P2PKH, P2WPKH, P2SH or P2WSH) that is involved in the timed\n // out request.\n // Only one method can add to this mapping:\n // - `notifyRedemptionTimeout` which puts the redemption key to this\n // mapping based on a timed out request stored previously in\n // `pendingRedemptions` mapping.\n // Only one method can remove entries from this mapping:\n // - `submitRedemptionProof` in case the timed out redemption request\n // was a part of the proven transaction.\n mapping(uint256 => Redemption.RedemptionRequest) timedOutRedemptions;\n // Collection of all submitted fraud challenges indexed by challenge\n // key built as `keccak256(walletPublicKey|sighash)`.\n mapping(uint256 => Fraud.FraudChallenge) fraudChallenges;\n // Collection of main UTXOs that are honestly spent indexed by\n // `keccak256(fundingTxHash | fundingOutputIndex)`. The `fundingTxHash`\n // is `bytes32` (ordered as in Bitcoin internally) and\n // `fundingOutputIndex` an `uint32`. A main UTXO is considered honestly\n // spent if it was used as an input of a transaction that have been\n // proven in the Bridge.\n mapping(uint256 => bool) spentMainUTXOs;\n // Maps the 20-byte wallet public key hash (computed using Bitcoin\n // HASH160 over the compressed ECDSA public key) to the basic wallet\n // information like state and pending redemptions value.\n mapping(bytes20 => Wallets.Wallet) registeredWallets;\n // Reserved storage space in case we need to add more variables.\n // The convention from OpenZeppelin suggests the storage space should\n // add up to 50 slots. Here we want to have more slots as there are\n // planned upgrades of the Bridge contract. If more entires are added to\n // the struct in the upcoming versions we need to reduce the array size.\n // See https://docs.openzeppelin.com/contracts/4.x/upgradeable#storage_gaps\n // slither-disable-next-line unused-state\n uint256[50] __gap;\n }\n\n event DepositParametersUpdated(\n uint64 depositDustThreshold,\n uint64 depositTreasuryFeeDivisor,\n uint64 depositTxMaxFee,\n uint32 depositRevealAheadPeriod\n );\n\n event RedemptionParametersUpdated(\n uint64 redemptionDustThreshold,\n uint64 redemptionTreasuryFeeDivisor,\n uint64 redemptionTxMaxFee,\n uint64 redemptionTxMaxTotalFee,\n uint32 redemptionTimeout,\n uint96 redemptionTimeoutSlashingAmount,\n uint32 redemptionTimeoutNotifierRewardMultiplier\n );\n\n event MovingFundsParametersUpdated(\n uint64 movingFundsTxMaxTotalFee,\n uint64 movingFundsDustThreshold,\n uint32 movingFundsTimeoutResetDelay,\n uint32 movingFundsTimeout,\n uint96 movingFundsTimeoutSlashingAmount,\n uint32 movingFundsTimeoutNotifierRewardMultiplier,\n uint16 movingFundsCommitmentGasOffset,\n uint64 movedFundsSweepTxMaxTotalFee,\n uint32 movedFundsSweepTimeout,\n uint96 movedFundsSweepTimeoutSlashingAmount,\n uint32 movedFundsSweepTimeoutNotifierRewardMultiplier\n );\n\n event WalletParametersUpdated(\n uint32 walletCreationPeriod,\n uint64 walletCreationMinBtcBalance,\n uint64 walletCreationMaxBtcBalance,\n uint64 walletClosureMinBtcBalance,\n uint32 walletMaxAge,\n uint64 walletMaxBtcTransfer,\n uint32 walletClosingPeriod\n );\n\n event FraudParametersUpdated(\n uint96 fraudChallengeDepositAmount,\n uint32 fraudChallengeDefeatTimeout,\n uint96 fraudSlashingAmount,\n uint32 fraudNotifierRewardMultiplier\n );\n\n event TreasuryUpdated(address treasury);\n\n /// @notice Updates parameters of deposits.\n /// @param _depositDustThreshold New value of the deposit dust threshold in\n /// satoshis. It is the minimal amount that can be requested to\n //// deposit. Value of this parameter must take into account the value\n /// of `depositTreasuryFeeDivisor` and `depositTxMaxFee` parameters\n /// in order to make requests that can incur the treasury and\n /// transaction fee and still satisfy the depositor.\n /// @param _depositTreasuryFeeDivisor New value of the treasury fee divisor.\n /// It is the divisor used to compute the treasury fee taken from\n /// each deposit and transferred to the treasury upon sweep proof\n /// submission. That fee is computed as follows:\n /// `treasuryFee = depositedAmount / depositTreasuryFeeDivisor`\n /// For example, if the treasury fee needs to be 2% of each deposit,\n /// the `depositTreasuryFeeDivisor` should be set to `50`\n /// because `1/50 = 0.02 = 2%`.\n /// @param _depositTxMaxFee New value of the deposit tx max fee in satoshis.\n /// It is the maximum amount of BTC transaction fee that can\n /// be incurred by each swept deposit being part of the given sweep\n /// transaction. If the maximum BTC transaction fee is exceeded,\n /// such transaction is considered a fraud.\n /// @param _depositRevealAheadPeriod New value of the deposit reveal ahead\n /// period parameter in seconds. It defines the length of the period\n /// that must be preserved between the deposit reveal time and the\n /// deposit refund locktime.\n /// @dev Requirements:\n /// - Deposit dust threshold must be greater than zero,\n /// - Deposit dust threshold must be greater than deposit TX max fee,\n /// - Deposit transaction max fee must be greater than zero.\n function updateDepositParameters(\n Storage storage self,\n uint64 _depositDustThreshold,\n uint64 _depositTreasuryFeeDivisor,\n uint64 _depositTxMaxFee,\n uint32 _depositRevealAheadPeriod\n ) internal {\n require(\n _depositDustThreshold > 0,\n \"Deposit dust threshold must be greater than zero\"\n );\n\n require(\n _depositDustThreshold > _depositTxMaxFee,\n \"Deposit dust threshold must be greater than deposit TX max fee\"\n );\n\n require(\n _depositTxMaxFee > 0,\n \"Deposit transaction max fee must be greater than zero\"\n );\n\n self.depositDustThreshold = _depositDustThreshold;\n self.depositTreasuryFeeDivisor = _depositTreasuryFeeDivisor;\n self.depositTxMaxFee = _depositTxMaxFee;\n self.depositRevealAheadPeriod = _depositRevealAheadPeriod;\n\n emit DepositParametersUpdated(\n _depositDustThreshold,\n _depositTreasuryFeeDivisor,\n _depositTxMaxFee,\n _depositRevealAheadPeriod\n );\n }\n\n /// @notice Updates parameters of redemptions.\n /// @param _redemptionDustThreshold New value of the redemption dust\n /// threshold in satoshis. It is the minimal amount that can be\n /// requested for redemption. Value of this parameter must take into\n /// account the value of `redemptionTreasuryFeeDivisor` and\n /// `redemptionTxMaxFee` parameters in order to make requests that\n /// can incur the treasury and transaction fee and still satisfy the\n /// redeemer.\n /// @param _redemptionTreasuryFeeDivisor New value of the redemption\n /// treasury fee divisor. It is the divisor used to compute the\n /// treasury fee taken from each redemption request and transferred\n /// to the treasury upon successful request finalization. That fee is\n /// computed as follows:\n /// `treasuryFee = requestedAmount / redemptionTreasuryFeeDivisor`\n /// For example, if the treasury fee needs to be 2% of each\n /// redemption request, the `redemptionTreasuryFeeDivisor` should\n /// be set to `50` because `1/50 = 0.02 = 2%`.\n /// @param _redemptionTxMaxFee New value of the redemption transaction max\n /// fee in satoshis. It is the maximum amount of BTC transaction fee\n /// that can be incurred by each redemption request being part of the\n /// given redemption transaction. If the maximum BTC transaction fee\n /// is exceeded, such transaction is considered a fraud.\n /// This is a per-redemption output max fee for the redemption\n /// transaction.\n /// @param _redemptionTxMaxTotalFee New value of the redemption transaction\n /// max total fee in satoshis. It is the maximum amount of the total\n /// BTC transaction fee that is acceptable in a single redemption\n /// transaction. This is a _total_ max fee for the entire redemption\n /// transaction.\n /// @param _redemptionTimeout New value of the redemption timeout in seconds.\n /// It is the time after which the redemption request can be reported\n /// as timed out. It is counted from the moment when the redemption\n /// request was created via `requestRedemption` call. Reported timed\n /// out requests are cancelled and locked TBTC is returned to the\n /// redeemer in full amount.\n /// @param _redemptionTimeoutSlashingAmount New value of the redemption\n /// timeout slashing amount in T, it is the amount slashed from each\n /// wallet member for redemption timeout.\n /// @param _redemptionTimeoutNotifierRewardMultiplier New value of the\n /// redemption timeout notifier reward multiplier as percentage,\n /// it determines the percentage of the notifier reward from the\n /// staking contact the notifier of a redemption timeout receives.\n /// The value must be in the range [0, 100].\n /// @dev Requirements:\n /// - Redemption dust threshold must be greater than moving funds dust\n /// threshold,\n /// - Redemption dust threshold must be greater than the redemption TX\n /// max fee,\n /// - Redemption transaction max fee must be greater than zero,\n /// - Redemption transaction max total fee must be greater than or\n /// equal to the redemption transaction per-request max fee,\n /// - Redemption timeout must be greater than zero,\n /// - Redemption timeout notifier reward multiplier must be in the\n /// range [0, 100].\n function updateRedemptionParameters(\n Storage storage self,\n uint64 _redemptionDustThreshold,\n uint64 _redemptionTreasuryFeeDivisor,\n uint64 _redemptionTxMaxFee,\n uint64 _redemptionTxMaxTotalFee,\n uint32 _redemptionTimeout,\n uint96 _redemptionTimeoutSlashingAmount,\n uint32 _redemptionTimeoutNotifierRewardMultiplier\n ) internal {\n require(\n _redemptionDustThreshold > self.movingFundsDustThreshold,\n \"Redemption dust threshold must be greater than moving funds dust threshold\"\n );\n\n require(\n _redemptionDustThreshold > _redemptionTxMaxFee,\n \"Redemption dust threshold must be greater than redemption TX max fee\"\n );\n\n require(\n _redemptionTxMaxFee > 0,\n \"Redemption transaction max fee must be greater than zero\"\n );\n\n require(\n _redemptionTxMaxTotalFee >= _redemptionTxMaxFee,\n \"Redemption transaction max total fee must be greater than or equal to the redemption transaction per-request max fee\"\n );\n\n require(\n _redemptionTimeout > 0,\n \"Redemption timeout must be greater than zero\"\n );\n\n require(\n _redemptionTimeoutNotifierRewardMultiplier <= 100,\n \"Redemption timeout notifier reward multiplier must be in the range [0, 100]\"\n );\n\n self.redemptionDustThreshold = _redemptionDustThreshold;\n self.redemptionTreasuryFeeDivisor = _redemptionTreasuryFeeDivisor;\n self.redemptionTxMaxFee = _redemptionTxMaxFee;\n self.redemptionTxMaxTotalFee = _redemptionTxMaxTotalFee;\n self.redemptionTimeout = _redemptionTimeout;\n self.redemptionTimeoutSlashingAmount = _redemptionTimeoutSlashingAmount;\n self\n .redemptionTimeoutNotifierRewardMultiplier = _redemptionTimeoutNotifierRewardMultiplier;\n\n emit RedemptionParametersUpdated(\n _redemptionDustThreshold,\n _redemptionTreasuryFeeDivisor,\n _redemptionTxMaxFee,\n _redemptionTxMaxTotalFee,\n _redemptionTimeout,\n _redemptionTimeoutSlashingAmount,\n _redemptionTimeoutNotifierRewardMultiplier\n );\n }\n\n /// @notice Updates parameters of moving funds.\n /// @param _movingFundsTxMaxTotalFee New value of the moving funds transaction\n /// max total fee in satoshis. It is the maximum amount of the total\n /// BTC transaction fee that is acceptable in a single moving funds\n /// transaction. This is a _total_ max fee for the entire moving\n /// funds transaction.\n /// @param _movingFundsDustThreshold New value of the moving funds dust\n /// threshold. It is the minimal satoshi amount that makes sense to\n /// be transferred during the moving funds process. Moving funds\n /// wallets having their BTC balance below that value can begin\n /// closing immediately as transferring such a low value may not be\n /// possible due to BTC network fees.\n /// @param _movingFundsTimeoutResetDelay New value of the moving funds\n /// timeout reset delay in seconds. It is the time after which the\n /// moving funds timeout can be reset in case the target wallet\n /// commitment cannot be submitted due to a lack of live wallets\n /// in the system. It is counted from the moment when the wallet\n /// was requested to move their funds and switched to the MovingFunds\n /// state or from the moment the timeout was reset the last time.\n /// @param _movingFundsTimeout New value of the moving funds timeout in\n /// seconds. It is the time after which the moving funds process can\n /// be reported as timed out. It is counted from the moment when the\n /// wallet was requested to move their funds and switched to the\n /// MovingFunds state.\n /// @param _movingFundsTimeoutSlashingAmount New value of the moving funds\n /// timeout slashing amount in T, it is the amount slashed from each\n /// wallet member for moving funds timeout.\n /// @param _movingFundsTimeoutNotifierRewardMultiplier New value of the\n /// moving funds timeout notifier reward multiplier as percentage,\n /// it determines the percentage of the notifier reward from the\n /// staking contact the notifier of a moving funds timeout receives.\n /// The value must be in the range [0, 100].\n /// @param _movingFundsCommitmentGasOffset New value of the gas offset for\n /// moving funds target wallet commitment transaction gas costs\n /// reimbursement.\n /// @param _movedFundsSweepTxMaxTotalFee New value of the moved funds sweep\n /// transaction max total fee in satoshis. It is the maximum amount\n /// of the total BTC transaction fee that is acceptable in a single\n /// moved funds sweep transaction. This is a _total_ max fee for the\n /// entire moved funds sweep transaction.\n /// @param _movedFundsSweepTimeout New value of the moved funds sweep\n /// timeout in seconds. It is the time after which the moved funds\n /// sweep process can be reported as timed out. It is counted from\n /// the moment when the wallet was requested to sweep the received\n /// funds.\n /// @param _movedFundsSweepTimeoutSlashingAmount New value of the moved\n /// funds sweep timeout slashing amount in T, it is the amount\n /// slashed from each wallet member for moved funds sweep timeout.\n /// @param _movedFundsSweepTimeoutNotifierRewardMultiplier New value of\n /// the moved funds sweep timeout notifier reward multiplier as\n /// percentage, it determines the percentage of the notifier reward\n /// from the staking contact the notifier of a moved funds sweep\n /// timeout receives. The value must be in the range [0, 100].\n /// @dev Requirements:\n /// - Moving funds transaction max total fee must be greater than zero,\n /// - Moving funds dust threshold must be greater than zero and lower\n /// than the redemption dust threshold,\n /// - Moving funds timeout reset delay must be greater than zero,\n /// - Moving funds timeout must be greater than the moving funds\n /// timeout reset delay,\n /// - Moving funds timeout notifier reward multiplier must be in the\n /// range [0, 100],\n /// - Moved funds sweep transaction max total fee must be greater than zero,\n /// - Moved funds sweep timeout must be greater than zero,\n /// - Moved funds sweep timeout notifier reward multiplier must be in the\n /// range [0, 100].\n function updateMovingFundsParameters(\n Storage storage self,\n uint64 _movingFundsTxMaxTotalFee,\n uint64 _movingFundsDustThreshold,\n uint32 _movingFundsTimeoutResetDelay,\n uint32 _movingFundsTimeout,\n uint96 _movingFundsTimeoutSlashingAmount,\n uint32 _movingFundsTimeoutNotifierRewardMultiplier,\n uint16 _movingFundsCommitmentGasOffset,\n uint64 _movedFundsSweepTxMaxTotalFee,\n uint32 _movedFundsSweepTimeout,\n uint96 _movedFundsSweepTimeoutSlashingAmount,\n uint32 _movedFundsSweepTimeoutNotifierRewardMultiplier\n ) internal {\n require(\n _movingFundsTxMaxTotalFee > 0,\n \"Moving funds transaction max total fee must be greater than zero\"\n );\n\n require(\n _movingFundsDustThreshold > 0 &&\n _movingFundsDustThreshold < self.redemptionDustThreshold,\n \"Moving funds dust threshold must be greater than zero and lower than redemption dust threshold\"\n );\n\n require(\n _movingFundsTimeoutResetDelay > 0,\n \"Moving funds timeout reset delay must be greater than zero\"\n );\n\n require(\n _movingFundsTimeout > _movingFundsTimeoutResetDelay,\n \"Moving funds timeout must be greater than its reset delay\"\n );\n\n require(\n _movingFundsTimeoutNotifierRewardMultiplier <= 100,\n \"Moving funds timeout notifier reward multiplier must be in the range [0, 100]\"\n );\n\n require(\n _movedFundsSweepTxMaxTotalFee > 0,\n \"Moved funds sweep transaction max total fee must be greater than zero\"\n );\n\n require(\n _movedFundsSweepTimeout > 0,\n \"Moved funds sweep timeout must be greater than zero\"\n );\n\n require(\n _movedFundsSweepTimeoutNotifierRewardMultiplier <= 100,\n \"Moved funds sweep timeout notifier reward multiplier must be in the range [0, 100]\"\n );\n\n self.movingFundsTxMaxTotalFee = _movingFundsTxMaxTotalFee;\n self.movingFundsDustThreshold = _movingFundsDustThreshold;\n self.movingFundsTimeoutResetDelay = _movingFundsTimeoutResetDelay;\n self.movingFundsTimeout = _movingFundsTimeout;\n self\n .movingFundsTimeoutSlashingAmount = _movingFundsTimeoutSlashingAmount;\n self\n .movingFundsTimeoutNotifierRewardMultiplier = _movingFundsTimeoutNotifierRewardMultiplier;\n self.movingFundsCommitmentGasOffset = _movingFundsCommitmentGasOffset;\n self.movedFundsSweepTxMaxTotalFee = _movedFundsSweepTxMaxTotalFee;\n self.movedFundsSweepTimeout = _movedFundsSweepTimeout;\n self\n .movedFundsSweepTimeoutSlashingAmount = _movedFundsSweepTimeoutSlashingAmount;\n self\n .movedFundsSweepTimeoutNotifierRewardMultiplier = _movedFundsSweepTimeoutNotifierRewardMultiplier;\n\n emit MovingFundsParametersUpdated(\n _movingFundsTxMaxTotalFee,\n _movingFundsDustThreshold,\n _movingFundsTimeoutResetDelay,\n _movingFundsTimeout,\n _movingFundsTimeoutSlashingAmount,\n _movingFundsTimeoutNotifierRewardMultiplier,\n _movingFundsCommitmentGasOffset,\n _movedFundsSweepTxMaxTotalFee,\n _movedFundsSweepTimeout,\n _movedFundsSweepTimeoutSlashingAmount,\n _movedFundsSweepTimeoutNotifierRewardMultiplier\n );\n }\n\n /// @notice Updates parameters of wallets.\n /// @param _walletCreationPeriod New value of the wallet creation period in\n /// seconds, determines how frequently a new wallet creation can be\n /// requested.\n /// @param _walletCreationMinBtcBalance New value of the wallet minimum BTC\n /// balance in satoshi, used to decide about wallet creation.\n /// @param _walletCreationMaxBtcBalance New value of the wallet maximum BTC\n /// balance in satoshi, used to decide about wallet creation.\n /// @param _walletClosureMinBtcBalance New value of the wallet minimum BTC\n /// balance in satoshi, used to decide about wallet closure.\n /// @param _walletMaxAge New value of the wallet maximum age in seconds,\n /// indicates the maximum age of a wallet in seconds, after which\n /// the wallet moving funds process can be requested.\n /// @param _walletMaxBtcTransfer New value of the wallet maximum BTC transfer\n /// in satoshi, determines the maximum amount that can be transferred\n /// to a single target wallet during the moving funds process.\n /// @param _walletClosingPeriod New value of the wallet closing period in\n /// seconds, determines the length of the wallet closing period,\n // i.e. the period when the wallet remains in the Closing state\n // and can be subject of deposit fraud challenges.\n /// @dev Requirements:\n /// - Wallet maximum BTC balance must be greater than the wallet\n /// minimum BTC balance,\n /// - Wallet maximum BTC transfer must be greater than zero,\n /// - Wallet closing period must be greater than zero.\n function updateWalletParameters(\n Storage storage self,\n uint32 _walletCreationPeriod,\n uint64 _walletCreationMinBtcBalance,\n uint64 _walletCreationMaxBtcBalance,\n uint64 _walletClosureMinBtcBalance,\n uint32 _walletMaxAge,\n uint64 _walletMaxBtcTransfer,\n uint32 _walletClosingPeriod\n ) internal {\n require(\n _walletCreationMaxBtcBalance > _walletCreationMinBtcBalance,\n \"Wallet creation maximum BTC balance must be greater than the creation minimum BTC balance\"\n );\n require(\n _walletMaxBtcTransfer > 0,\n \"Wallet maximum BTC transfer must be greater than zero\"\n );\n require(\n _walletClosingPeriod > 0,\n \"Wallet closing period must be greater than zero\"\n );\n\n self.walletCreationPeriod = _walletCreationPeriod;\n self.walletCreationMinBtcBalance = _walletCreationMinBtcBalance;\n self.walletCreationMaxBtcBalance = _walletCreationMaxBtcBalance;\n self.walletClosureMinBtcBalance = _walletClosureMinBtcBalance;\n self.walletMaxAge = _walletMaxAge;\n self.walletMaxBtcTransfer = _walletMaxBtcTransfer;\n self.walletClosingPeriod = _walletClosingPeriod;\n\n emit WalletParametersUpdated(\n _walletCreationPeriod,\n _walletCreationMinBtcBalance,\n _walletCreationMaxBtcBalance,\n _walletClosureMinBtcBalance,\n _walletMaxAge,\n _walletMaxBtcTransfer,\n _walletClosingPeriod\n );\n }\n\n /// @notice Updates parameters related to frauds.\n /// @param _fraudChallengeDepositAmount New value of the fraud challenge\n /// deposit amount in wei, it is the amount of ETH the party\n /// challenging the wallet for fraud needs to deposit.\n /// @param _fraudChallengeDefeatTimeout New value of the challenge defeat\n /// timeout in seconds, it is the amount of time the wallet has to\n /// defeat a fraud challenge. The value must be greater than zero.\n /// @param _fraudSlashingAmount New value of the fraud slashing amount in T,\n /// it is the amount slashed from each wallet member for committing\n /// a fraud.\n /// @param _fraudNotifierRewardMultiplier New value of the fraud notifier\n /// reward multiplier as percentage, it determines the percentage of\n /// the notifier reward from the staking contact the notifier of\n /// a fraud receives. The value must be in the range [0, 100].\n /// @dev Requirements:\n /// - Fraud challenge defeat timeout must be greater than 0,\n /// - Fraud notifier reward multiplier must be in the range [0, 100].\n function updateFraudParameters(\n Storage storage self,\n uint96 _fraudChallengeDepositAmount,\n uint32 _fraudChallengeDefeatTimeout,\n uint96 _fraudSlashingAmount,\n uint32 _fraudNotifierRewardMultiplier\n ) internal {\n require(\n _fraudChallengeDefeatTimeout > 0,\n \"Fraud challenge defeat timeout must be greater than zero\"\n );\n\n require(\n _fraudNotifierRewardMultiplier <= 100,\n \"Fraud notifier reward multiplier must be in the range [0, 100]\"\n );\n\n self.fraudChallengeDepositAmount = _fraudChallengeDepositAmount;\n self.fraudChallengeDefeatTimeout = _fraudChallengeDefeatTimeout;\n self.fraudSlashingAmount = _fraudSlashingAmount;\n self.fraudNotifierRewardMultiplier = _fraudNotifierRewardMultiplier;\n\n emit FraudParametersUpdated(\n _fraudChallengeDepositAmount,\n _fraudChallengeDefeatTimeout,\n _fraudSlashingAmount,\n _fraudNotifierRewardMultiplier\n );\n }\n\n /// @notice Updates treasury address. The treasury receives the system fees.\n /// @param _treasury New value of the treasury address.\n /// @dev The treasury address must not be 0x0.\n function updateTreasury(Storage storage self, address _treasury) internal {\n require(_treasury != address(0), \"Treasury address must not be 0x0\");\n\n self.treasury = _treasury;\n emit TreasuryUpdated(_treasury);\n }\n}\n" + }, + "contracts/bridge/Deposit.sol": { + "content": "// SPDX-License-Identifier: GPL-3.0-only\n\n// ██████████████ ▐████▌ ██████████████\n// ██████████████ ▐████▌ ██████████████\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ██████████████ ▐████▌ ██████████████\n// ██████████████ ▐████▌ ██████████████\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n\npragma solidity 0.8.17;\n\nimport {BTCUtils} from \"@keep-network/bitcoin-spv-sol/contracts/BTCUtils.sol\";\nimport {BytesLib} from \"@keep-network/bitcoin-spv-sol/contracts/BytesLib.sol\";\n\nimport \"./BitcoinTx.sol\";\nimport \"./BridgeState.sol\";\nimport \"./Wallets.sol\";\n\n/// @title Bridge deposit\n/// @notice The library handles the logic for revealing Bitcoin deposits to\n/// the Bridge.\n/// @dev The depositor puts together a P2SH or P2WSH address to deposit the\n/// funds. This script is unique to each depositor and looks like this:\n///\n/// ```\n/// DROP\n/// DROP\n/// DUP HASH160 EQUAL\n/// IF\n/// CHECKSIG\n/// ELSE\n/// DUP HASH160 EQUALVERIFY\n/// CHECKLOCKTIMEVERIFY DROP\n/// CHECKSIG\n/// ENDIF\n/// ```\n///\n/// Since each depositor has their own Ethereum address and their own\n/// blinding factor, each depositor’s script is unique, and the hash\n/// of each depositor’s script is unique.\nlibrary Deposit {\n using BTCUtils for bytes;\n using BytesLib for bytes;\n\n /// @notice Represents data which must be revealed by the depositor during\n /// deposit reveal.\n struct DepositRevealInfo {\n // Index of the funding output belonging to the funding transaction.\n uint32 fundingOutputIndex;\n // The blinding factor as 8 bytes. Byte endianness doesn't matter\n // as this factor is not interpreted as uint. The blinding factor allows\n // to distinguish deposits from the same depositor.\n bytes8 blindingFactor;\n // The compressed Bitcoin public key (33 bytes and 02 or 03 prefix)\n // of the deposit's wallet hashed in the HASH160 Bitcoin opcode style.\n bytes20 walletPubKeyHash;\n // The compressed Bitcoin public key (33 bytes and 02 or 03 prefix)\n // that can be used to make the deposit refund after the refund\n // locktime passes. Hashed in the HASH160 Bitcoin opcode style.\n bytes20 refundPubKeyHash;\n // The refund locktime (4-byte LE). Interpreted according to locktime\n // parsing rules described in:\n // https://developer.bitcoin.org/devguide/transactions.html#locktime-and-sequence-number\n // and used with OP_CHECKLOCKTIMEVERIFY opcode as described in:\n // https://github.com/bitcoin/bips/blob/master/bip-0065.mediawiki\n bytes4 refundLocktime;\n // Address of the Bank vault to which the deposit is routed to.\n // Optional, can be 0x0. The vault must be trusted by the Bridge.\n address vault;\n // This struct doesn't contain `__gap` property as the structure is not\n // stored, it is used as a function's calldata argument.\n }\n\n /// @notice Represents tBTC deposit request data.\n struct DepositRequest {\n // Ethereum depositor address.\n address depositor;\n // Deposit amount in satoshi.\n uint64 amount;\n // UNIX timestamp the deposit was revealed at.\n // XXX: Unsigned 32-bit int unix seconds, will break February 7th 2106.\n uint32 revealedAt;\n // Address of the Bank vault the deposit is routed to.\n // Optional, can be 0x0.\n address vault;\n // Treasury TBTC fee in satoshi at the moment of deposit reveal.\n uint64 treasuryFee;\n // UNIX timestamp the deposit was swept at. Note this is not the\n // time when the deposit was swept on the Bitcoin chain but actually\n // the time when the sweep proof was delivered to the Ethereum chain.\n // XXX: Unsigned 32-bit int unix seconds, will break February 7th 2106.\n uint32 sweptAt;\n // This struct doesn't contain `__gap` property as the structure is stored\n // in a mapping, mappings store values in different slots and they are\n // not contiguous with other values.\n }\n\n event DepositRevealed(\n bytes32 fundingTxHash,\n uint32 fundingOutputIndex,\n address indexed depositor,\n uint64 amount,\n bytes8 blindingFactor,\n bytes20 indexed walletPubKeyHash,\n bytes20 refundPubKeyHash,\n bytes4 refundLocktime,\n address vault\n );\n\n /// @notice Used by the depositor to reveal information about their P2(W)SH\n /// Bitcoin deposit to the Bridge on Ethereum chain. The off-chain\n /// wallet listens for revealed deposit events and may decide to\n /// include the revealed deposit in the next executed sweep.\n /// Information about the Bitcoin deposit can be revealed before or\n /// after the Bitcoin transaction with P2(W)SH deposit is mined on\n /// the Bitcoin chain. Worth noting, the gas cost of this function\n /// scales with the number of P2(W)SH transaction inputs and\n /// outputs. The deposit may be routed to one of the trusted vaults.\n /// When a deposit is routed to a vault, vault gets notified when\n /// the deposit gets swept and it may execute the appropriate action.\n /// @param fundingTx Bitcoin funding transaction data, see `BitcoinTx.Info`.\n /// @param reveal Deposit reveal data, see `RevealInfo struct.\n /// @dev Requirements:\n /// - This function must be called by the same Ethereum address as the\n /// one used in the P2(W)SH BTC deposit transaction as a depositor,\n /// - `reveal.walletPubKeyHash` must identify a `Live` wallet,\n /// - `reveal.vault` must be 0x0 or point to a trusted vault,\n /// - `reveal.fundingOutputIndex` must point to the actual P2(W)SH\n /// output of the BTC deposit transaction,\n /// - `reveal.blindingFactor` must be the blinding factor used in the\n /// P2(W)SH BTC deposit transaction,\n /// - `reveal.walletPubKeyHash` must be the wallet pub key hash used in\n /// the P2(W)SH BTC deposit transaction,\n /// - `reveal.refundPubKeyHash` must be the refund pub key hash used in\n /// the P2(W)SH BTC deposit transaction,\n /// - `reveal.refundLocktime` must be the refund locktime used in the\n /// P2(W)SH BTC deposit transaction,\n /// - BTC deposit for the given `fundingTxHash`, `fundingOutputIndex`\n /// can be revealed only one time.\n ///\n /// If any of these requirements is not met, the wallet _must_ refuse\n /// to sweep the deposit and the depositor has to wait until the\n /// deposit script unlocks to receive their BTC back.\n function revealDeposit(\n BridgeState.Storage storage self,\n BitcoinTx.Info calldata fundingTx,\n DepositRevealInfo calldata reveal\n ) external {\n require(\n self.registeredWallets[reveal.walletPubKeyHash].state ==\n Wallets.WalletState.Live,\n \"Wallet must be in Live state\"\n );\n\n require(\n reveal.vault == address(0) || self.isVaultTrusted[reveal.vault],\n \"Vault is not trusted\"\n );\n\n if (self.depositRevealAheadPeriod > 0) {\n validateDepositRefundLocktime(self, reveal.refundLocktime);\n }\n\n bytes memory expectedScript = abi.encodePacked(\n hex\"14\", // Byte length of depositor Ethereum address.\n msg.sender,\n hex\"75\", // OP_DROP\n hex\"08\", // Byte length of blinding factor value.\n reveal.blindingFactor,\n hex\"75\", // OP_DROP\n hex\"76\", // OP_DUP\n hex\"a9\", // OP_HASH160\n hex\"14\", // Byte length of a compressed Bitcoin public key hash.\n reveal.walletPubKeyHash,\n hex\"87\", // OP_EQUAL\n hex\"63\", // OP_IF\n hex\"ac\", // OP_CHECKSIG\n hex\"67\", // OP_ELSE\n hex\"76\", // OP_DUP\n hex\"a9\", // OP_HASH160\n hex\"14\", // Byte length of a compressed Bitcoin public key hash.\n reveal.refundPubKeyHash,\n hex\"88\", // OP_EQUALVERIFY\n hex\"04\", // Byte length of refund locktime value.\n reveal.refundLocktime,\n hex\"b1\", // OP_CHECKLOCKTIMEVERIFY\n hex\"75\", // OP_DROP\n hex\"ac\", // OP_CHECKSIG\n hex\"68\" // OP_ENDIF\n );\n\n bytes memory fundingOutput = fundingTx\n .outputVector\n .extractOutputAtIndex(reveal.fundingOutputIndex);\n bytes memory fundingOutputHash = fundingOutput.extractHash();\n\n if (fundingOutputHash.length == 20) {\n // A 20-byte output hash is used by P2SH. That hash is constructed\n // by applying OP_HASH160 on the locking script. A 20-byte output\n // hash is used as well by P2PKH and P2WPKH (OP_HASH160 on the\n // public key). However, since we compare the actual output hash\n // with an expected locking script hash, this check will succeed only\n // for P2SH transaction type with expected script hash value. For\n // P2PKH and P2WPKH, it will fail on the output hash comparison with\n // the expected locking script hash.\n require(\n fundingOutputHash.slice20(0) == expectedScript.hash160View(),\n \"Wrong 20-byte script hash\"\n );\n } else if (fundingOutputHash.length == 32) {\n // A 32-byte output hash is used by P2WSH. That hash is constructed\n // by applying OP_SHA256 on the locking script.\n require(\n fundingOutputHash.toBytes32() == sha256(expectedScript),\n \"Wrong 32-byte script hash\"\n );\n } else {\n revert(\"Wrong script hash length\");\n }\n\n // Resulting TX hash is in native Bitcoin little-endian format.\n bytes32 fundingTxHash = abi\n .encodePacked(\n fundingTx.version,\n fundingTx.inputVector,\n fundingTx.outputVector,\n fundingTx.locktime\n )\n .hash256View();\n\n DepositRequest storage deposit = self.deposits[\n uint256(\n keccak256(\n abi.encodePacked(fundingTxHash, reveal.fundingOutputIndex)\n )\n )\n ];\n require(deposit.revealedAt == 0, \"Deposit already revealed\");\n\n uint64 fundingOutputAmount = fundingOutput.extractValue();\n\n require(\n fundingOutputAmount >= self.depositDustThreshold,\n \"Deposit amount too small\"\n );\n\n deposit.amount = fundingOutputAmount;\n deposit.depositor = msg.sender;\n /* solhint-disable-next-line not-rely-on-time */\n deposit.revealedAt = uint32(block.timestamp);\n deposit.vault = reveal.vault;\n deposit.treasuryFee = self.depositTreasuryFeeDivisor > 0\n ? fundingOutputAmount / self.depositTreasuryFeeDivisor\n : 0;\n // slither-disable-next-line reentrancy-events\n emit DepositRevealed(\n fundingTxHash,\n reveal.fundingOutputIndex,\n msg.sender,\n fundingOutputAmount,\n reveal.blindingFactor,\n reveal.walletPubKeyHash,\n reveal.refundPubKeyHash,\n reveal.refundLocktime,\n reveal.vault\n );\n }\n\n /// @notice Validates the deposit refund locktime. The validation passes\n /// successfully only if the deposit reveal is done respectively\n /// earlier than the moment when the deposit refund locktime is\n /// reached, i.e. the deposit become refundable. Reverts otherwise.\n /// @param refundLocktime The deposit refund locktime as 4-byte LE.\n /// @dev Requirements:\n /// - `refundLocktime` as integer must be >= 500M\n /// - `refundLocktime` must denote a timestamp that is at least\n /// `depositRevealAheadPeriod` seconds later than the moment\n /// of `block.timestamp`\n function validateDepositRefundLocktime(\n BridgeState.Storage storage self,\n bytes4 refundLocktime\n ) internal view {\n // Convert the refund locktime byte array to a LE integer. This is\n // the moment in time when the deposit become refundable.\n uint32 depositRefundableTimestamp = BTCUtils.reverseUint32(\n uint32(refundLocktime)\n );\n // According to https://developer.bitcoin.org/devguide/transactions.html#locktime-and-sequence-number\n // the locktime is parsed as a block number if less than 500M. We always\n // want to parse the locktime as an Unix timestamp so we allow only for\n // values bigger than or equal to 500M.\n require(\n depositRefundableTimestamp >= 500 * 1e6,\n \"Refund locktime must be a value >= 500M\"\n );\n // The deposit must be revealed before it becomes refundable.\n // This is because the sweeping wallet needs to have some time to\n // sweep the deposit and avoid a potential competition with the\n // depositor making the deposit refund.\n require(\n /* solhint-disable-next-line not-rely-on-time */\n block.timestamp + self.depositRevealAheadPeriod <=\n depositRefundableTimestamp,\n \"Deposit refund locktime is too close\"\n );\n }\n}\n" + }, + "contracts/bridge/DepositSweep.sol": { + "content": "// SPDX-License-Identifier: GPL-3.0-only\n\n// ██████████████ ▐████▌ ██████████████\n// ██████████████ ▐████▌ ██████████████\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ██████████████ ▐████▌ ██████████████\n// ██████████████ ▐████▌ ██████████████\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n\npragma solidity 0.8.17;\n\nimport {BTCUtils} from \"@keep-network/bitcoin-spv-sol/contracts/BTCUtils.sol\";\n\nimport \"./BitcoinTx.sol\";\nimport \"./BridgeState.sol\";\nimport \"./Wallets.sol\";\n\nimport \"../bank/Bank.sol\";\n\n/// @title Bridge deposit sweep\n/// @notice The library handles the logic for sweeping transactions revealed to\n/// the Bridge\n/// @dev Bridge active wallet periodically signs a transaction that unlocks all\n/// of the valid, revealed deposits above the dust threshold, combines them\n/// into a single UTXO with the existing main wallet UTXO, and relocks\n/// those transactions without a 30-day refund clause to the same wallet.\n/// This has two main effects: it consolidates the UTXO set and it disables\n/// the refund. Balances of depositors in the Bank are increased when the\n/// SPV sweep proof is submitted to the Bridge.\nlibrary DepositSweep {\n using BridgeState for BridgeState.Storage;\n using BitcoinTx for BridgeState.Storage;\n\n using BTCUtils for bytes;\n\n /// @notice Represents temporary information needed during the processing\n /// of the deposit sweep Bitcoin transaction inputs. This structure\n /// is an internal one and should not be exported outside of the\n /// deposit sweep transaction processing code.\n /// @dev Allows to mitigate \"stack too deep\" errors on EVM.\n struct DepositSweepTxInputsProcessingInfo {\n // Input vector of the deposit sweep Bitcoin transaction. It is\n // assumed the vector's structure is valid so it must be validated\n // using e.g. `BTCUtils.validateVin` function before being used\n // during the processing. The validation is usually done as part\n // of the `BitcoinTx.validateProof` call that checks the SPV proof.\n bytes sweepTxInputVector;\n // Data of the wallet's main UTXO. If no main UTXO exists for the given\n // sweeping wallet, this parameter's fields should be zeroed to bypass\n // the main UTXO validation\n BitcoinTx.UTXO mainUtxo;\n // Address of the vault where all swept deposits should be routed to.\n // It is used to validate whether all swept deposits have been revealed\n // with the same `vault` parameter. It is an optional parameter.\n // Set to zero address if deposits are not routed to a vault.\n address vault;\n // This struct doesn't contain `__gap` property as the structure is not\n // stored, it is used as a function's memory argument.\n }\n\n /// @notice Represents an outcome of the sweep Bitcoin transaction\n /// inputs processing.\n struct DepositSweepTxInputsInfo {\n // Sum of all inputs values i.e. all deposits and main UTXO value,\n // if present.\n uint256 inputsTotalValue;\n // Addresses of depositors who performed processed deposits. Ordered in\n // the same order as deposits inputs in the input vector. Size of this\n // array is either equal to the number of inputs (main UTXO doesn't\n // exist) or less by one (main UTXO exists and is pointed by one of\n // the inputs).\n address[] depositors;\n // Amounts of deposits corresponding to processed deposits. Ordered in\n // the same order as deposits inputs in the input vector. Size of this\n // array is either equal to the number of inputs (main UTXO doesn't\n // exist) or less by one (main UTXO exists and is pointed by one of\n // the inputs).\n uint256[] depositedAmounts;\n // Values of the treasury fee corresponding to processed deposits.\n // Ordered in the same order as deposits inputs in the input vector.\n // Size of this array is either equal to the number of inputs (main\n // UTXO doesn't exist) or less by one (main UTXO exists and is pointed\n // by one of the inputs).\n uint256[] treasuryFees;\n // This struct doesn't contain `__gap` property as the structure is not\n // stored, it is used as a function's memory argument.\n }\n\n event DepositsSwept(bytes20 walletPubKeyHash, bytes32 sweepTxHash);\n\n /// @notice Used by the wallet to prove the BTC deposit sweep transaction\n /// and to update Bank balances accordingly. Sweep is only accepted\n /// if it satisfies SPV proof.\n ///\n /// The function is performing Bank balance updates by first\n /// computing the Bitcoin fee for the sweep transaction. The fee is\n /// divided evenly between all swept deposits. Each depositor\n /// receives a balance in the bank equal to the amount inferred\n /// during the reveal transaction, minus their fee share.\n ///\n /// It is possible to prove the given sweep only one time.\n /// @param sweepTx Bitcoin sweep transaction data.\n /// @param sweepProof Bitcoin sweep proof data.\n /// @param mainUtxo Data of the wallet's main UTXO, as currently known on\n /// the Ethereum chain. If no main UTXO exists for the given wallet,\n /// this parameter is ignored.\n /// @param vault Optional address of the vault where all swept deposits\n /// should be routed to. All deposits swept as part of the transaction\n /// must have their `vault` parameters set to the same address.\n /// If this parameter is set to an address of a trusted vault, swept\n /// deposits are routed to that vault.\n /// If this parameter is set to the zero address or to an address\n /// of a non-trusted vault, swept deposits are not routed to a\n /// vault but depositors' balances are increased in the Bank\n /// individually.\n /// @dev Requirements:\n /// - `sweepTx` components must match the expected structure. See\n /// `BitcoinTx.Info` docs for reference. Their values must exactly\n /// correspond to appropriate Bitcoin transaction fields to produce\n /// a provable transaction hash,\n /// - The `sweepTx` should represent a Bitcoin transaction with 1..n\n /// inputs. If the wallet has no main UTXO, all n inputs should\n /// correspond to P2(W)SH revealed deposits UTXOs. If the wallet has\n /// an existing main UTXO, one of the n inputs must point to that\n /// main UTXO and remaining n-1 inputs should correspond to P2(W)SH\n /// revealed deposits UTXOs. That transaction must have only\n /// one P2(W)PKH output locking funds on the 20-byte wallet public\n /// key hash,\n /// - All revealed deposits that are swept by `sweepTx` must have\n /// their `vault` parameters set to the same address as the address\n /// passed in the `vault` function parameter,\n /// - `sweepProof` components must match the expected structure. See\n /// `BitcoinTx.Proof` docs for reference. The `bitcoinHeaders`\n /// field must contain a valid number of block headers, not less\n /// than the `txProofDifficultyFactor` contract constant,\n /// - `mainUtxo` components must point to the recent main UTXO\n /// of the given wallet, as currently known on the Ethereum chain.\n /// If there is no main UTXO, this parameter is ignored.\n function submitDepositSweepProof(\n BridgeState.Storage storage self,\n BitcoinTx.Info calldata sweepTx,\n BitcoinTx.Proof calldata sweepProof,\n BitcoinTx.UTXO calldata mainUtxo,\n address vault\n ) external {\n // Wallet state validation is performed in the\n // `resolveDepositSweepingWallet` function.\n\n // The actual transaction proof is performed here. After that point, we\n // can assume the transaction happened on Bitcoin chain and has\n // a sufficient number of confirmations as determined by\n // `txProofDifficultyFactor` constant.\n bytes32 sweepTxHash = self.validateProof(sweepTx, sweepProof);\n\n // Process sweep transaction output and extract its target wallet\n // public key hash and value.\n (\n bytes20 walletPubKeyHash,\n uint64 sweepTxOutputValue\n ) = processDepositSweepTxOutput(self, sweepTx.outputVector);\n\n (\n Wallets.Wallet storage wallet,\n BitcoinTx.UTXO memory resolvedMainUtxo\n ) = resolveDepositSweepingWallet(self, walletPubKeyHash, mainUtxo);\n\n // Process sweep transaction inputs and extract all information needed\n // to perform deposit bookkeeping.\n DepositSweepTxInputsInfo\n memory inputsInfo = processDepositSweepTxInputs(\n self,\n DepositSweepTxInputsProcessingInfo(\n sweepTx.inputVector,\n resolvedMainUtxo,\n vault\n )\n );\n\n // Helper variable that will hold the sum of treasury fees paid by\n // all deposits.\n uint256 totalTreasuryFee = 0;\n\n // Determine the transaction fee that should be incurred by each deposit\n // and the indivisible remainder that should be additionally incurred\n // by the last deposit.\n (\n uint256 depositTxFee,\n uint256 depositTxFeeRemainder\n ) = depositSweepTxFeeDistribution(\n inputsInfo.inputsTotalValue,\n sweepTxOutputValue,\n inputsInfo.depositedAmounts.length\n );\n\n // Make sure the highest value of the deposit transaction fee does not\n // exceed the maximum value limited by the governable parameter.\n require(\n depositTxFee + depositTxFeeRemainder <= self.depositTxMaxFee,\n \"Transaction fee is too high\"\n );\n\n // Reduce each deposit amount by treasury fee and transaction fee.\n for (uint256 i = 0; i < inputsInfo.depositedAmounts.length; i++) {\n // The last deposit should incur the deposit transaction fee\n // remainder.\n uint256 depositTxFeeIncurred = i ==\n inputsInfo.depositedAmounts.length - 1\n ? depositTxFee + depositTxFeeRemainder\n : depositTxFee;\n\n // There is no need to check whether\n // `inputsInfo.depositedAmounts[i] - inputsInfo.treasuryFees[i] - txFee > 0`\n // since the `depositDustThreshold` should force that condition\n // to be always true.\n inputsInfo.depositedAmounts[i] =\n inputsInfo.depositedAmounts[i] -\n inputsInfo.treasuryFees[i] -\n depositTxFeeIncurred;\n totalTreasuryFee += inputsInfo.treasuryFees[i];\n }\n\n // Record this sweep data and assign them to the wallet public key hash\n // as new main UTXO. Transaction output index is always 0 as sweep\n // transaction always contains only one output.\n wallet.mainUtxoHash = keccak256(\n abi.encodePacked(sweepTxHash, uint32(0), sweepTxOutputValue)\n );\n\n // slither-disable-next-line reentrancy-events\n emit DepositsSwept(walletPubKeyHash, sweepTxHash);\n\n if (vault != address(0) && self.isVaultTrusted[vault]) {\n // If the `vault` address is not zero and belongs to a trusted\n // vault, route the deposits to that vault.\n self.bank.increaseBalanceAndCall(\n vault,\n inputsInfo.depositors,\n inputsInfo.depositedAmounts\n );\n } else {\n // If the `vault` address is zero or belongs to a non-trusted\n // vault, increase balances in the Bank individually for each\n // depositor.\n self.bank.increaseBalances(\n inputsInfo.depositors,\n inputsInfo.depositedAmounts\n );\n }\n\n // Pass the treasury fee to the treasury address.\n if (totalTreasuryFee > 0) {\n self.bank.increaseBalance(self.treasury, totalTreasuryFee);\n }\n }\n\n /// @notice Resolves sweeping wallet based on the provided wallet public key\n /// hash. Validates the wallet state and current main UTXO, as\n /// currently known on the Ethereum chain.\n /// @param walletPubKeyHash public key hash of the wallet proving the sweep\n /// Bitcoin transaction.\n /// @param mainUtxo Data of the wallet's main UTXO, as currently known on\n /// the Ethereum chain. If no main UTXO exists for the given wallet,\n /// this parameter is ignored.\n /// @return wallet Data of the sweeping wallet.\n /// @return resolvedMainUtxo The actual main UTXO of the sweeping wallet\n /// resolved by cross-checking the `mainUtxo` parameter with\n /// the chain state. If the validation went well, this is the\n /// plain-text main UTXO corresponding to the `wallet.mainUtxoHash`.\n /// @dev Requirements:\n /// - Sweeping wallet must be either in Live or MovingFunds state,\n /// - If the main UTXO of the sweeping wallet exists in the storage,\n /// the passed `mainUTXO` parameter must be equal to the stored one.\n function resolveDepositSweepingWallet(\n BridgeState.Storage storage self,\n bytes20 walletPubKeyHash,\n BitcoinTx.UTXO calldata mainUtxo\n )\n internal\n view\n returns (\n Wallets.Wallet storage wallet,\n BitcoinTx.UTXO memory resolvedMainUtxo\n )\n {\n wallet = self.registeredWallets[walletPubKeyHash];\n\n Wallets.WalletState walletState = wallet.state;\n require(\n walletState == Wallets.WalletState.Live ||\n walletState == Wallets.WalletState.MovingFunds,\n \"Wallet must be in Live or MovingFunds state\"\n );\n\n // Check if the main UTXO for given wallet exists. If so, validate\n // passed main UTXO data against the stored hash and use them for\n // further processing. If no main UTXO exists, use empty data.\n resolvedMainUtxo = BitcoinTx.UTXO(bytes32(0), 0, 0);\n bytes32 mainUtxoHash = wallet.mainUtxoHash;\n if (mainUtxoHash != bytes32(0)) {\n require(\n keccak256(\n abi.encodePacked(\n mainUtxo.txHash,\n mainUtxo.txOutputIndex,\n mainUtxo.txOutputValue\n )\n ) == mainUtxoHash,\n \"Invalid main UTXO data\"\n );\n resolvedMainUtxo = mainUtxo;\n }\n }\n\n /// @notice Processes the Bitcoin sweep transaction output vector by\n /// extracting the single output and using it to gain additional\n /// information required for further processing (e.g. value and\n /// wallet public key hash).\n /// @param sweepTxOutputVector Bitcoin sweep transaction output vector.\n /// This function assumes vector's structure is valid so it must be\n /// validated using e.g. `BTCUtils.validateVout` function before\n /// it is passed here.\n /// @return walletPubKeyHash 20-byte wallet public key hash.\n /// @return value 8-byte sweep transaction output value.\n function processDepositSweepTxOutput(\n BridgeState.Storage storage self,\n bytes memory sweepTxOutputVector\n ) internal view returns (bytes20 walletPubKeyHash, uint64 value) {\n // To determine the total number of sweep transaction outputs, we need to\n // parse the compactSize uint (VarInt) the output vector is prepended by.\n // That compactSize uint encodes the number of vector elements using the\n // format presented in:\n // https://developer.bitcoin.org/reference/transactions.html#compactsize-unsigned-integers\n // We don't need asserting the compactSize uint is parseable since it\n // was already checked during `validateVout` validation.\n // See `BitcoinTx.outputVector` docs for more details.\n (, uint256 outputsCount) = sweepTxOutputVector.parseVarInt();\n require(\n outputsCount == 1,\n \"Sweep transaction must have a single output\"\n );\n\n bytes memory output = sweepTxOutputVector.extractOutputAtIndex(0);\n walletPubKeyHash = self.extractPubKeyHash(output);\n value = output.extractValue();\n\n return (walletPubKeyHash, value);\n }\n\n /// @notice Processes the Bitcoin sweep transaction input vector. It\n /// extracts each input and tries to obtain associated deposit or\n /// main UTXO data, depending on the input type. Reverts\n /// if one of the inputs cannot be recognized as a pointer to a\n /// revealed deposit or expected main UTXO.\n /// This function also marks each processed deposit as swept.\n /// @return resultInfo Outcomes of the processing.\n function processDepositSweepTxInputs(\n BridgeState.Storage storage self,\n DepositSweepTxInputsProcessingInfo memory processInfo\n ) internal returns (DepositSweepTxInputsInfo memory resultInfo) {\n // If the passed `mainUtxo` parameter's values are zeroed, the main UTXO\n // for the given wallet doesn't exist and it is not expected to be\n // included in the sweep transaction input vector.\n bool mainUtxoExpected = processInfo.mainUtxo.txHash != bytes32(0);\n bool mainUtxoFound = false;\n\n // Determining the total number of sweep transaction inputs in the same\n // way as for number of outputs. See `BitcoinTx.inputVector` docs for\n // more details.\n (uint256 inputsCompactSizeUintLength, uint256 inputsCount) = processInfo\n .sweepTxInputVector\n .parseVarInt();\n\n // To determine the first input starting index, we must jump over\n // the compactSize uint which prepends the input vector. One byte\n // must be added because `BtcUtils.parseVarInt` does not include\n // compactSize uint tag in the returned length.\n //\n // For >= 0 && <= 252, `BTCUtils.determineVarIntDataLengthAt`\n // returns `0`, so we jump over one byte of compactSize uint.\n //\n // For >= 253 && <= 0xffff there is `0xfd` tag,\n // `BTCUtils.determineVarIntDataLengthAt` returns `2` (no\n // tag byte included) so we need to jump over 1+2 bytes of\n // compactSize uint.\n //\n // Please refer `BTCUtils` library and compactSize uint\n // docs in `BitcoinTx` library for more details.\n uint256 inputStartingIndex = 1 + inputsCompactSizeUintLength;\n\n // Determine the swept deposits count. If main UTXO is NOT expected,\n // all inputs should be deposits. If main UTXO is expected, one input\n // should point to that main UTXO.\n resultInfo.depositors = new address[](\n !mainUtxoExpected ? inputsCount : inputsCount - 1\n );\n resultInfo.depositedAmounts = new uint256[](\n resultInfo.depositors.length\n );\n resultInfo.treasuryFees = new uint256[](resultInfo.depositors.length);\n\n // Initialize helper variables.\n uint256 processedDepositsCount = 0;\n\n // Inputs processing loop.\n for (uint256 i = 0; i < inputsCount; i++) {\n (\n bytes32 outpointTxHash,\n uint32 outpointIndex,\n uint256 inputLength\n ) = parseDepositSweepTxInputAt(\n processInfo.sweepTxInputVector,\n inputStartingIndex\n );\n\n Deposit.DepositRequest storage deposit = self.deposits[\n uint256(\n keccak256(abi.encodePacked(outpointTxHash, outpointIndex))\n )\n ];\n\n if (deposit.revealedAt != 0) {\n // If we entered here, that means the input was identified as\n // a revealed deposit.\n require(deposit.sweptAt == 0, \"Deposit already swept\");\n\n require(\n deposit.vault == processInfo.vault,\n \"Deposit should be routed to another vault\"\n );\n\n if (processedDepositsCount == resultInfo.depositors.length) {\n // If this condition is true, that means a deposit input\n // took place of an expected main UTXO input.\n // In other words, there is no expected main UTXO\n // input and all inputs come from valid, revealed deposits.\n revert(\n \"Expected main UTXO not present in sweep transaction inputs\"\n );\n }\n\n /* solhint-disable-next-line not-rely-on-time */\n deposit.sweptAt = uint32(block.timestamp);\n\n resultInfo.depositors[processedDepositsCount] = deposit\n .depositor;\n resultInfo.depositedAmounts[processedDepositsCount] = deposit\n .amount;\n resultInfo.inputsTotalValue += resultInfo.depositedAmounts[\n processedDepositsCount\n ];\n resultInfo.treasuryFees[processedDepositsCount] = deposit\n .treasuryFee;\n\n processedDepositsCount++;\n } else if (\n mainUtxoExpected != mainUtxoFound &&\n processInfo.mainUtxo.txHash == outpointTxHash &&\n processInfo.mainUtxo.txOutputIndex == outpointIndex\n ) {\n // If we entered here, that means the input was identified as\n // the expected main UTXO.\n resultInfo.inputsTotalValue += processInfo\n .mainUtxo\n .txOutputValue;\n mainUtxoFound = true;\n\n // Main UTXO used as an input, mark it as spent.\n self.spentMainUTXOs[\n uint256(\n keccak256(\n abi.encodePacked(outpointTxHash, outpointIndex)\n )\n )\n ] = true;\n } else {\n revert(\"Unknown input type\");\n }\n\n // Make the `inputStartingIndex` pointing to the next input by\n // increasing it by current input's length.\n inputStartingIndex += inputLength;\n }\n\n // Construction of the input processing loop guarantees that:\n // `processedDepositsCount == resultInfo.depositors.length == resultInfo.depositedAmounts.length`\n // is always true at this point. We just use the first variable\n // to assert the total count of swept deposit is bigger than zero.\n require(\n processedDepositsCount > 0,\n \"Sweep transaction must process at least one deposit\"\n );\n\n // Assert the main UTXO was used as one of current sweep's inputs if\n // it was actually expected.\n require(\n mainUtxoExpected == mainUtxoFound,\n \"Expected main UTXO not present in sweep transaction inputs\"\n );\n\n return resultInfo;\n }\n\n /// @notice Parses a Bitcoin transaction input starting at the given index.\n /// @param inputVector Bitcoin transaction input vector.\n /// @param inputStartingIndex Index the given input starts at.\n /// @return outpointTxHash 32-byte hash of the Bitcoin transaction which is\n /// pointed in the given input's outpoint.\n /// @return outpointIndex 4-byte index of the Bitcoin transaction output\n /// which is pointed in the given input's outpoint.\n /// @return inputLength Byte length of the given input.\n /// @dev This function assumes vector's structure is valid so it must be\n /// validated using e.g. `BTCUtils.validateVin` function before it\n /// is passed here.\n function parseDepositSweepTxInputAt(\n bytes memory inputVector,\n uint256 inputStartingIndex\n )\n internal\n pure\n returns (\n bytes32 outpointTxHash,\n uint32 outpointIndex,\n uint256 inputLength\n )\n {\n outpointTxHash = inputVector.extractInputTxIdLeAt(inputStartingIndex);\n\n outpointIndex = BTCUtils.reverseUint32(\n uint32(inputVector.extractTxIndexLeAt(inputStartingIndex))\n );\n\n inputLength = inputVector.determineInputLengthAt(inputStartingIndex);\n\n return (outpointTxHash, outpointIndex, inputLength);\n }\n\n /// @notice Determines the distribution of the sweep transaction fee\n /// over swept deposits.\n /// @param sweepTxInputsTotalValue Total value of all sweep transaction inputs.\n /// @param sweepTxOutputValue Value of the sweep transaction output.\n /// @param depositsCount Count of the deposits swept by the sweep transaction.\n /// @return depositTxFee Transaction fee per deposit determined by evenly\n /// spreading the divisible part of the sweep transaction fee\n /// over all deposits.\n /// @return depositTxFeeRemainder The indivisible part of the sweep\n /// transaction fee than cannot be distributed over all deposits.\n /// @dev It is up to the caller to decide how the remainder should be\n /// counted in. This function only computes its value.\n function depositSweepTxFeeDistribution(\n uint256 sweepTxInputsTotalValue,\n uint256 sweepTxOutputValue,\n uint256 depositsCount\n )\n internal\n pure\n returns (uint256 depositTxFee, uint256 depositTxFeeRemainder)\n {\n // The sweep transaction fee is just the difference between inputs\n // amounts sum and the output amount.\n uint256 sweepTxFee = sweepTxInputsTotalValue - sweepTxOutputValue;\n // Compute the indivisible remainder that remains after dividing the\n // sweep transaction fee over all deposits evenly.\n depositTxFeeRemainder = sweepTxFee % depositsCount;\n // Compute the transaction fee per deposit by dividing the sweep\n // transaction fee (reduced by the remainder) by the number of deposits.\n depositTxFee = (sweepTxFee - depositTxFeeRemainder) / depositsCount;\n\n return (depositTxFee, depositTxFeeRemainder);\n }\n}\n" + }, + "contracts/bridge/EcdsaLib.sol": { + "content": "// SPDX-License-Identifier: GPL-3.0-only\n\n// ██████████████ ▐████▌ ██████████████\n// ██████████████ ▐████▌ ██████████████\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ██████████████ ▐████▌ ██████████████\n// ██████████████ ▐████▌ ██████████████\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n\npragma solidity 0.8.17;\n\nimport \"@keep-network/bitcoin-spv-sol/contracts/BytesLib.sol\";\n\nlibrary EcdsaLib {\n using BytesLib for bytes;\n\n /// @notice Converts public key X and Y coordinates (32-byte each) to a\n /// compressed public key (33-byte). Compressed public key is X\n /// coordinate prefixed with `02` or `03` based on the Y coordinate parity.\n /// It is expected that the uncompressed public key is stripped\n /// (i.e. it is not prefixed with `04`).\n /// @param x Wallet's public key's X coordinate.\n /// @param y Wallet's public key's Y coordinate.\n /// @return Compressed public key (33-byte), prefixed with `02` or `03`.\n function compressPublicKey(bytes32 x, bytes32 y)\n internal\n pure\n returns (bytes memory)\n {\n bytes1 prefix;\n if (uint256(y) % 2 == 0) {\n prefix = hex\"02\";\n } else {\n prefix = hex\"03\";\n }\n\n return bytes.concat(prefix, x);\n }\n}\n" + }, + "contracts/bridge/Fraud.sol": { + "content": "// SPDX-License-Identifier: GPL-3.0-only\n\n// ██████████████ ▐████▌ ██████████████\n// ██████████████ ▐████▌ ██████████████\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ██████████████ ▐████▌ ██████████████\n// ██████████████ ▐████▌ ██████████████\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n\npragma solidity 0.8.17;\n\nimport {BytesLib} from \"@keep-network/bitcoin-spv-sol/contracts/BytesLib.sol\";\nimport {BTCUtils} from \"@keep-network/bitcoin-spv-sol/contracts/BTCUtils.sol\";\nimport {CheckBitcoinSigs} from \"@keep-network/bitcoin-spv-sol/contracts/CheckBitcoinSigs.sol\";\n\nimport \"./BitcoinTx.sol\";\nimport \"./EcdsaLib.sol\";\nimport \"./BridgeState.sol\";\nimport \"./Heartbeat.sol\";\nimport \"./MovingFunds.sol\";\nimport \"./Wallets.sol\";\n\n/// @title Bridge fraud\n/// @notice The library handles the logic for challenging Bridge wallets that\n/// committed fraud.\n/// @dev Anyone can submit a fraud challenge indicating that a UTXO being under\n/// the wallet control was unlocked by the wallet but was not used\n/// according to the protocol rules. That means the wallet signed\n/// a transaction input pointing to that UTXO and there is a unique\n/// sighash and signature pair associated with that input.\n///\n/// In order to defeat the challenge, the same wallet public key and\n/// signature must be provided as were used to calculate the sighash during\n/// the challenge. The wallet provides the preimage which produces sighash\n/// used to generate the ECDSA signature that is the subject of the fraud\n/// claim.\n///\n/// The fraud challenge defeat attempt will succeed if the inputs in the\n/// preimage are considered honestly spent by the wallet. Therefore the\n/// transaction spending the UTXO must be proven in the Bridge before\n/// a challenge defeat is called.\n///\n/// Another option is when a malicious wallet member used a signed heartbeat\n/// message periodically produced by the wallet off-chain to challenge the\n/// wallet for a fraud. Anyone from the wallet can defeat the challenge by\n/// proving the sighash and signature were produced for a heartbeat message\n/// following a strict format.\nlibrary Fraud {\n using Wallets for BridgeState.Storage;\n\n using BytesLib for bytes;\n using BTCUtils for bytes;\n using BTCUtils for uint32;\n using EcdsaLib for bytes;\n\n struct FraudChallenge {\n // The address of the party challenging the wallet.\n address challenger;\n // The amount of ETH the challenger deposited.\n uint256 depositAmount;\n // The timestamp the challenge was submitted at.\n // XXX: Unsigned 32-bit int unix seconds, will break February 7th 2106.\n uint32 reportedAt;\n // The flag indicating whether the challenge has been resolved.\n bool resolved;\n // This struct doesn't contain `__gap` property as the structure is stored\n // in a mapping, mappings store values in different slots and they are\n // not contiguous with other values.\n }\n\n event FraudChallengeSubmitted(\n bytes20 indexed walletPubKeyHash,\n bytes32 sighash,\n uint8 v,\n bytes32 r,\n bytes32 s\n );\n\n event FraudChallengeDefeated(\n bytes20 indexed walletPubKeyHash,\n bytes32 sighash\n );\n\n event FraudChallengeDefeatTimedOut(\n bytes20 indexed walletPubKeyHash,\n // Sighash calculated as a Bitcoin's hash256 (double sha2) of:\n // - a preimage of a transaction spending UTXO according to the protocol\n // rules OR\n // - a valid heartbeat message produced by the wallet off-chain.\n bytes32 sighash\n );\n\n /// @notice Submits a fraud challenge indicating that a UTXO being under\n /// wallet control was unlocked by the wallet but was not used\n /// according to the protocol rules. That means the wallet signed\n /// a transaction input pointing to that UTXO and there is a unique\n /// sighash and signature pair associated with that input. This\n /// function uses those parameters to create a fraud accusation that\n /// proves a given transaction input unlocking the given UTXO was\n /// actually signed by the wallet. This function cannot determine\n /// whether the transaction was actually broadcast and the input was\n /// consumed in a fraudulent way so it just opens a challenge period\n /// during which the wallet can defeat the challenge by submitting\n /// proof of a transaction that consumes the given input according\n /// to protocol rules. To prevent spurious allegations, the caller\n /// must deposit ETH that is returned back upon justified fraud\n /// challenge or confiscated otherwise.\n /// @param walletPublicKey The public key of the wallet in the uncompressed\n /// and unprefixed format (64 bytes).\n /// @param preimageSha256 The hash that was generated by applying SHA-256\n /// one time over the preimage used during input signing. The preimage\n /// is a serialized subset of the transaction and its structure\n /// depends on the transaction input (see BIP-143 for reference).\n /// Notice that applying SHA-256 over the `preimageSha256` results\n /// in `sighash`. The path from `preimage` to `sighash` looks like\n /// this:\n /// preimage -> (SHA-256) -> preimageSha256 -> (SHA-256) -> sighash.\n /// @param signature Bitcoin signature in the R/S/V format\n /// @dev Requirements:\n /// - Wallet behind `walletPublicKey` must be in Live or MovingFunds\n /// or Closing state,\n /// - The challenger must send appropriate amount of ETH used as\n /// fraud challenge deposit,\n /// - The signature (represented by r, s and v) must be generated by\n /// the wallet behind `walletPubKey` during signing of `sighash`\n /// which was calculated from `preimageSha256`,\n /// - Wallet can be challenged for the given signature only once.\n function submitFraudChallenge(\n BridgeState.Storage storage self,\n bytes calldata walletPublicKey,\n bytes memory preimageSha256,\n BitcoinTx.RSVSignature calldata signature\n ) external {\n require(\n msg.value >= self.fraudChallengeDepositAmount,\n \"The amount of ETH deposited is too low\"\n );\n\n // To prevent ECDSA signature forgery `sighash` must be calculated\n // inside the function and not passed as a function parameter.\n // Signature forgery could result in a wrongful fraud accusation\n // against a wallet.\n bytes32 sighash = sha256(preimageSha256);\n\n require(\n CheckBitcoinSigs.checkSig(\n walletPublicKey,\n sighash,\n signature.v,\n signature.r,\n signature.s\n ),\n \"Signature verification failure\"\n );\n\n bytes memory compressedWalletPublicKey = EcdsaLib.compressPublicKey(\n walletPublicKey.slice32(0),\n walletPublicKey.slice32(32)\n );\n bytes20 walletPubKeyHash = compressedWalletPublicKey.hash160View();\n\n Wallets.Wallet storage wallet = self.registeredWallets[\n walletPubKeyHash\n ];\n\n require(\n wallet.state == Wallets.WalletState.Live ||\n wallet.state == Wallets.WalletState.MovingFunds ||\n wallet.state == Wallets.WalletState.Closing,\n \"Wallet must be in Live or MovingFunds or Closing state\"\n );\n\n uint256 challengeKey = uint256(\n keccak256(abi.encodePacked(walletPublicKey, sighash))\n );\n\n FraudChallenge storage challenge = self.fraudChallenges[challengeKey];\n require(challenge.reportedAt == 0, \"Fraud challenge already exists\");\n\n challenge.challenger = msg.sender;\n challenge.depositAmount = msg.value;\n /* solhint-disable-next-line not-rely-on-time */\n challenge.reportedAt = uint32(block.timestamp);\n challenge.resolved = false;\n // slither-disable-next-line reentrancy-events\n emit FraudChallengeSubmitted(\n walletPubKeyHash,\n sighash,\n signature.v,\n signature.r,\n signature.s\n );\n }\n\n /// @notice Allows to defeat a pending fraud challenge against a wallet if\n /// the transaction that spends the UTXO follows the protocol rules.\n /// In order to defeat the challenge the same `walletPublicKey` and\n /// signature (represented by `r`, `s` and `v`) must be provided as\n /// were used to calculate the sighash during input signing.\n /// The fraud challenge defeat attempt will only succeed if the\n /// inputs in the preimage are considered honestly spent by the\n /// wallet. Therefore the transaction spending the UTXO must be\n /// proven in the Bridge before a challenge defeat is called.\n /// If successfully defeated, the fraud challenge is marked as\n /// resolved and the amount of ether deposited by the challenger is\n /// sent to the treasury.\n /// @param walletPublicKey The public key of the wallet in the uncompressed\n /// and unprefixed format (64 bytes).\n /// @param preimage The preimage which produces sighash used to generate the\n /// ECDSA signature that is the subject of the fraud claim. It is a\n /// serialized subset of the transaction. The exact subset used as\n /// the preimage depends on the transaction input the signature is\n /// produced for. See BIP-143 for reference.\n /// @param witness Flag indicating whether the preimage was produced for a\n /// witness input. True for witness, false for non-witness input.\n /// @dev Requirements:\n /// - `walletPublicKey` and `sighash` calculated as `hash256(preimage)`\n /// must identify an open fraud challenge,\n /// - the preimage must be a valid preimage of a transaction generated\n /// according to the protocol rules and already proved in the Bridge,\n /// - before a defeat attempt is made the transaction that spends the\n /// given UTXO must be proven in the Bridge.\n function defeatFraudChallenge(\n BridgeState.Storage storage self,\n bytes calldata walletPublicKey,\n bytes calldata preimage,\n bool witness\n ) external {\n bytes32 sighash = preimage.hash256();\n\n uint256 challengeKey = uint256(\n keccak256(abi.encodePacked(walletPublicKey, sighash))\n );\n\n FraudChallenge storage challenge = self.fraudChallenges[challengeKey];\n\n require(challenge.reportedAt > 0, \"Fraud challenge does not exist\");\n require(\n !challenge.resolved,\n \"Fraud challenge has already been resolved\"\n );\n\n // Ensure SIGHASH_ALL type was used during signing, which is represented\n // by type value `1`.\n require(extractSighashType(preimage) == 1, \"Wrong sighash type\");\n\n uint256 utxoKey = witness\n ? extractUtxoKeyFromWitnessPreimage(preimage)\n : extractUtxoKeyFromNonWitnessPreimage(preimage);\n\n // Check that the UTXO key identifies a correctly spent UTXO.\n require(\n self.deposits[utxoKey].sweptAt > 0 ||\n self.spentMainUTXOs[utxoKey] ||\n self.movedFundsSweepRequests[utxoKey].state ==\n MovingFunds.MovedFundsSweepRequestState.Processed,\n \"Spent UTXO not found among correctly spent UTXOs\"\n );\n\n resolveFraudChallenge(self, walletPublicKey, challenge, sighash);\n }\n\n /// @notice Allows to defeat a pending fraud challenge against a wallet by\n /// proving the sighash and signature were produced for an off-chain\n /// wallet heartbeat message following a strict format.\n /// In order to defeat the challenge the same `walletPublicKey` and\n /// signature (represented by `r`, `s` and `v`) must be provided as\n /// were used to calculate the sighash during heartbeat message\n /// signing. The fraud challenge defeat attempt will only succeed if\n /// the signed message follows a strict format required for\n /// heartbeat messages. If successfully defeated, the fraud\n /// challenge is marked as resolved and the amount of ether\n /// deposited by the challenger is sent to the treasury.\n /// @param walletPublicKey The public key of the wallet in the uncompressed\n /// and unprefixed format (64 bytes),\n /// @param heartbeatMessage Off-chain heartbeat message meeting the heartbeat\n /// message format requirements which produces sighash used to\n /// generate the ECDSA signature that is the subject of the fraud\n /// claim.\n /// @dev Requirements:\n /// - `walletPublicKey` and `sighash` calculated as\n /// `hash256(heartbeatMessage)` must identify an open fraud challenge,\n /// - `heartbeatMessage` must follow a strict format of heartbeat\n /// messages.\n function defeatFraudChallengeWithHeartbeat(\n BridgeState.Storage storage self,\n bytes calldata walletPublicKey,\n bytes calldata heartbeatMessage\n ) external {\n bytes32 sighash = heartbeatMessage.hash256();\n\n uint256 challengeKey = uint256(\n keccak256(abi.encodePacked(walletPublicKey, sighash))\n );\n\n FraudChallenge storage challenge = self.fraudChallenges[challengeKey];\n\n require(challenge.reportedAt > 0, \"Fraud challenge does not exist\");\n require(\n !challenge.resolved,\n \"Fraud challenge has already been resolved\"\n );\n\n require(\n Heartbeat.isValidHeartbeatMessage(heartbeatMessage),\n \"Not a valid heartbeat message\"\n );\n\n resolveFraudChallenge(self, walletPublicKey, challenge, sighash);\n }\n\n /// @notice Called only for successfully defeated fraud challenges.\n /// The fraud challenge is marked as resolved and the amount of\n /// ether deposited by the challenger is sent to the treasury.\n /// @dev Requirements:\n /// - Must be called only for successfully defeated fraud challenges.\n function resolveFraudChallenge(\n BridgeState.Storage storage self,\n bytes calldata walletPublicKey,\n FraudChallenge storage challenge,\n bytes32 sighash\n ) internal {\n // Mark the challenge as resolved as it was successfully defeated\n challenge.resolved = true;\n\n // Send the ether deposited by the challenger to the treasury\n /* solhint-disable avoid-low-level-calls */\n // slither-disable-next-line low-level-calls,unchecked-lowlevel,arbitrary-send\n self.treasury.call{gas: 100000, value: challenge.depositAmount}(\"\");\n /* solhint-enable avoid-low-level-calls */\n\n bytes memory compressedWalletPublicKey = EcdsaLib.compressPublicKey(\n walletPublicKey.slice32(0),\n walletPublicKey.slice32(32)\n );\n bytes20 walletPubKeyHash = compressedWalletPublicKey.hash160View();\n\n // slither-disable-next-line reentrancy-events\n emit FraudChallengeDefeated(walletPubKeyHash, sighash);\n }\n\n /// @notice Notifies about defeat timeout for the given fraud challenge.\n /// Can be called only if there was a fraud challenge identified by\n /// the provided `walletPublicKey` and `sighash` and it was not\n /// defeated on time. The amount of time that needs to pass after\n /// a fraud challenge is reported is indicated by the\n /// `challengeDefeatTimeout`. After a successful fraud challenge\n /// defeat timeout notification the fraud challenge is marked as\n /// resolved, the stake of each operator is slashed, the ether\n /// deposited is returned to the challenger and the challenger is\n /// rewarded.\n /// @param walletPublicKey The public key of the wallet in the uncompressed\n /// and unprefixed format (64 bytes).\n /// @param walletMembersIDs Identifiers of the wallet signing group members.\n /// @param preimageSha256 The hash that was generated by applying SHA-256\n /// one time over the preimage used during input signing. The preimage\n /// is a serialized subset of the transaction and its structure\n /// depends on the transaction input (see BIP-143 for reference).\n /// Notice that applying SHA-256 over the `preimageSha256` results\n /// in `sighash`. The path from `preimage` to `sighash` looks like\n /// this:\n /// preimage -> (SHA-256) -> preimageSha256 -> (SHA-256) -> sighash.\n /// @dev Requirements:\n /// - The wallet must be in the Live or MovingFunds or Closing or\n /// Terminated state,\n /// - The `walletPublicKey` and `sighash` calculated from\n /// `preimageSha256` must identify an open fraud challenge,\n /// - The expression `keccak256(abi.encode(walletMembersIDs))` must\n /// be exactly the same as the hash stored under `membersIdsHash`\n /// for the given `walletID`. Those IDs are not directly stored\n /// in the contract for gas efficiency purposes but they can be\n /// read from appropriate `DkgResultSubmitted` and `DkgResultApproved`\n /// events of the `WalletRegistry` contract,\n /// - The amount of time indicated by `challengeDefeatTimeout` must pass\n /// after the challenge was reported.\n function notifyFraudChallengeDefeatTimeout(\n BridgeState.Storage storage self,\n bytes calldata walletPublicKey,\n uint32[] calldata walletMembersIDs,\n bytes memory preimageSha256\n ) external {\n // Wallet state is validated in `notifyWalletFraudChallengeDefeatTimeout`.\n\n bytes32 sighash = sha256(preimageSha256);\n\n uint256 challengeKey = uint256(\n keccak256(abi.encodePacked(walletPublicKey, sighash))\n );\n\n FraudChallenge storage challenge = self.fraudChallenges[challengeKey];\n\n require(challenge.reportedAt > 0, \"Fraud challenge does not exist\");\n\n require(\n !challenge.resolved,\n \"Fraud challenge has already been resolved\"\n );\n\n require(\n /* solhint-disable-next-line not-rely-on-time */\n block.timestamp >=\n challenge.reportedAt + self.fraudChallengeDefeatTimeout,\n \"Fraud challenge defeat period did not time out yet\"\n );\n\n challenge.resolved = true;\n // Return the ether deposited by the challenger\n /* solhint-disable avoid-low-level-calls */\n // slither-disable-next-line low-level-calls,unchecked-lowlevel\n challenge.challenger.call{gas: 100000, value: challenge.depositAmount}(\n \"\"\n );\n /* solhint-enable avoid-low-level-calls */\n\n bytes memory compressedWalletPublicKey = EcdsaLib.compressPublicKey(\n walletPublicKey.slice32(0),\n walletPublicKey.slice32(32)\n );\n bytes20 walletPubKeyHash = compressedWalletPublicKey.hash160View();\n\n self.notifyWalletFraudChallengeDefeatTimeout(\n walletPubKeyHash,\n walletMembersIDs,\n challenge.challenger\n );\n\n // slither-disable-next-line reentrancy-events\n emit FraudChallengeDefeatTimedOut(walletPubKeyHash, sighash);\n }\n\n /// @notice Extracts the UTXO keys from the given preimage used during\n /// signing of a witness input.\n /// @param preimage The preimage which produces sighash used to generate the\n /// ECDSA signature that is the subject of the fraud claim. It is a\n /// serialized subset of the transaction. The exact subset used as\n /// the preimage depends on the transaction input the signature is\n /// produced for. See BIP-143 for reference\n /// @return utxoKey UTXO key that identifies spent input.\n function extractUtxoKeyFromWitnessPreimage(bytes calldata preimage)\n internal\n pure\n returns (uint256 utxoKey)\n {\n // The expected structure of the preimage created during signing of a\n // witness input:\n // - transaction version (4 bytes)\n // - hash of previous outpoints of all inputs (32 bytes)\n // - hash of sequences of all inputs (32 bytes)\n // - outpoint (hash + index) of the input being signed (36 bytes)\n // - the unlocking script of the input (variable length)\n // - value of the outpoint (8 bytes)\n // - sequence of the input being signed (4 bytes)\n // - hash of all outputs (32 bytes)\n // - transaction locktime (4 bytes)\n // - sighash type (4 bytes)\n\n // See Bitcoin's BIP-143 for reference:\n // https://github.com/bitcoin/bips/blob/master/bip-0143.mediawiki.\n\n // The outpoint (hash and index) is located at the constant offset of\n // 68 (4 + 32 + 32).\n bytes32 outpointTxHash = preimage.extractInputTxIdLeAt(68);\n uint32 outpointIndex = BTCUtils.reverseUint32(\n uint32(preimage.extractTxIndexLeAt(68))\n );\n\n return\n uint256(keccak256(abi.encodePacked(outpointTxHash, outpointIndex)));\n }\n\n /// @notice Extracts the UTXO key from the given preimage used during\n /// signing of a non-witness input.\n /// @param preimage The preimage which produces sighash used to generate the\n /// ECDSA signature that is the subject of the fraud claim. It is a\n /// serialized subset of the transaction. The exact subset used as\n /// the preimage depends on the transaction input the signature is\n /// produced for. See BIP-143 for reference.\n /// @return utxoKey UTXO key that identifies spent input.\n function extractUtxoKeyFromNonWitnessPreimage(bytes calldata preimage)\n internal\n pure\n returns (uint256 utxoKey)\n {\n // The expected structure of the preimage created during signing of a\n // non-witness input:\n // - transaction version (4 bytes)\n // - number of inputs written as compactSize uint (1 byte, 3 bytes,\n // 5 bytes or 9 bytes)\n // - for each input\n // - outpoint (hash and index) (36 bytes)\n // - unlocking script for the input being signed (variable length)\n // or `00` for all other inputs (1 byte)\n // - input sequence (4 bytes)\n // - number of outputs written as compactSize uint (1 byte, 3 bytes,\n // 5 bytes or 9 bytes)\n // - outputs (variable length)\n // - transaction locktime (4 bytes)\n // - sighash type (4 bytes)\n\n // See example for reference:\n // https://en.bitcoin.it/wiki/OP_CHECKSIG#Code_samples_and_raw_dumps.\n\n // The input data begins at the constant offset of 4 (the first 4 bytes\n // are for the transaction version).\n (uint256 inputsCompactSizeUintLength, uint256 inputsCount) = preimage\n .parseVarIntAt(4);\n\n // To determine the first input starting index, we must jump 4 bytes\n // over the transaction version length and the compactSize uint which\n // prepends the input vector. One byte must be added because\n // `BtcUtils.parseVarInt` does not include compactSize uint tag in the\n // returned length.\n //\n // For >= 0 && <= 252, `BTCUtils.determineVarIntDataLengthAt`\n // returns `0`, so we jump over one byte of compactSize uint.\n //\n // For >= 253 && <= 0xffff there is `0xfd` tag,\n // `BTCUtils.determineVarIntDataLengthAt` returns `2` (no\n // tag byte included) so we need to jump over 1+2 bytes of\n // compactSize uint.\n //\n // Please refer `BTCUtils` library and compactSize uint\n // docs in `BitcoinTx` library for more details.\n uint256 inputStartingIndex = 4 + 1 + inputsCompactSizeUintLength;\n\n for (uint256 i = 0; i < inputsCount; i++) {\n uint256 inputLength = preimage.determineInputLengthAt(\n inputStartingIndex\n );\n\n (, uint256 scriptSigLength) = preimage.extractScriptSigLenAt(\n inputStartingIndex\n );\n\n if (scriptSigLength > 0) {\n // The input this preimage was generated for was found.\n // All the other inputs in the preimage are marked with a null\n // scriptSig (\"00\") which has length of 1.\n bytes32 outpointTxHash = preimage.extractInputTxIdLeAt(\n inputStartingIndex\n );\n uint32 outpointIndex = BTCUtils.reverseUint32(\n uint32(preimage.extractTxIndexLeAt(inputStartingIndex))\n );\n\n utxoKey = uint256(\n keccak256(abi.encodePacked(outpointTxHash, outpointIndex))\n );\n\n break;\n }\n\n inputStartingIndex += inputLength;\n }\n\n return utxoKey;\n }\n\n /// @notice Extracts the sighash type from the given preimage.\n /// @param preimage Serialized subset of the transaction. See BIP-143 for\n /// reference.\n /// @dev Sighash type is stored as the last 4 bytes in the preimage (little\n /// endian).\n /// @return sighashType Sighash type as a 32-bit integer.\n function extractSighashType(bytes calldata preimage)\n internal\n pure\n returns (uint32 sighashType)\n {\n bytes4 sighashTypeBytes = preimage.slice4(preimage.length - 4);\n uint32 sighashTypeLE = uint32(sighashTypeBytes);\n return sighashTypeLE.reverseUint32();\n }\n}\n" + }, + "contracts/bridge/Heartbeat.sol": { + "content": "// SPDX-License-Identifier: GPL-3.0-only\n\n// ██████████████ ▐████▌ ██████████████\n// ██████████████ ▐████▌ ██████████████\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ██████████████ ▐████▌ ██████████████\n// ██████████████ ▐████▌ ██████████████\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n\npragma solidity 0.8.17;\n\nimport {BytesLib} from \"@keep-network/bitcoin-spv-sol/contracts/BytesLib.sol\";\n\n/// @title Bridge wallet heartbeat\n/// @notice The library establishes expected format for heartbeat messages\n/// signed by wallet ECDSA signing group. Heartbeat messages are\n/// constructed in such a way that they can not be used as a Bitcoin\n/// transaction preimages.\n/// @dev The smallest Bitcoin non-coinbase transaction is a one spending an\n/// OP_TRUE anyonecanspend output and creating 1 OP_TRUE anyonecanspend\n/// output. Such a transaction has 61 bytes (see `BitcoinTx` documentation):\n/// 4 bytes for version\n/// 1 byte for tx_in_count\n/// 36 bytes for tx_in.previous_output\n/// 1 byte for tx_in.script_bytes (value: 0)\n/// 0 bytes for tx_in.signature_script\n/// 4 bytes for tx_in.sequence\n/// 1 byte for tx_out_count\n/// 8 bytes for tx_out.value\n/// 1 byte for tx_out.pk_script_bytes\n/// 1 byte for tx_out.pk_script\n/// 4 bytes for lock_time\n///\n///\n/// The smallest Bitcoin coinbase transaction is a one creating\n/// 1 OP_TRUE anyonecanspend output and having an empty coinbase script.\n/// Such a transaction has 65 bytes:\n/// 4 bytes for version\n/// 1 byte for tx_in_count\n/// 32 bytes for tx_in.hash (all 0x00)\n/// 4 bytes for tx_in.index (all 0xff)\n/// 1 byte for tx_in.script_bytes (value: 0)\n/// 4 bytes for tx_in.height\n/// 0 byte for tx_in.coinbase_script\n/// 4 bytes for tx_in.sequence\n/// 1 byte for tx_out_count\n/// 8 bytes for tx_out.value\n/// 1 byte for tx_out.pk_script_bytes\n/// 1 byte for tx_out.pk_script\n/// 4 bytes for lock_time\n///\n///\n/// A SIGHASH flag is used to indicate which part of the transaction is\n/// signed by the ECDSA signature. There are currently 3 flags:\n/// SIGHASH_ALL, SIGHASH_NONE, SIGHASH_SINGLE, and different combinations\n/// of these flags.\n///\n/// No matter the SIGHASH flag and no matter the combination, the following\n/// fields from the transaction are always included in the constructed\n/// preimage:\n/// 4 bytes for version\n/// 36 bytes for tx_in.previous_output (or tx_in.hash + tx_in.index for coinbase)\n/// 4 bytes for lock_time\n///\n/// Additionally, the last 4 bytes of the preimage determines the SIGHASH\n/// flag.\n///\n/// This is enough to say there is no way the preimage could be shorter\n/// than 4 + 36 + 4 + 4 = 48 bytes.\n///\n/// For this reason, we construct the heartbeat message, as a 16-byte\n/// message. The first 8 bytes are 0xffffffffffffffff. The last 8 bytes\n/// are for an arbitrary uint64, being a signed heartbeat nonce (for\n/// example, the last Ethereum block hash).\n///\n/// The message being signed by the wallet when executing the heartbeat\n/// protocol should be Bitcoin's hash256 (double SHA-256) of the heartbeat\n/// message:\n/// heartbeat_sighash = hash256(heartbeat_message)\nlibrary Heartbeat {\n using BytesLib for bytes;\n\n /// @notice Determines if the signed byte array is a valid, non-fraudulent\n /// heartbeat message.\n /// @param message Message signed by the wallet. It is a potential heartbeat\n /// message, Bitcoin transaction preimage, or an arbitrary signed\n /// bytes.\n /// @dev Wallet heartbeat message must be exactly 16 bytes long with the first\n /// 8 bytes set to 0xffffffffffffffff.\n /// @return True if valid heartbeat message, false otherwise.\n function isValidHeartbeatMessage(bytes calldata message)\n internal\n pure\n returns (bool)\n {\n if (message.length != 16) {\n return false;\n }\n\n if (message.slice8(0) != 0xffffffffffffffff) {\n return false;\n }\n\n return true;\n }\n}\n" + }, + "contracts/bridge/IRelay.sol": { + "content": "// SPDX-License-Identifier: GPL-3.0-only\n\n// ██████████████ ▐████▌ ██████████████\n// ██████████████ ▐████▌ ██████████████\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ██████████████ ▐████▌ ██████████████\n// ██████████████ ▐████▌ ██████████████\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n\npragma solidity 0.8.17;\n\n/// @title Interface for the Bitcoin relay\n/// @notice Contains only the methods needed by tBTC v2. The Bitcoin relay\n/// provides the difficulty of the previous and current epoch. One\n/// difficulty epoch spans 2016 blocks.\ninterface IRelay {\n /// @notice Returns the difficulty of the current epoch.\n function getCurrentEpochDifficulty() external view returns (uint256);\n\n /// @notice Returns the difficulty of the previous epoch.\n function getPrevEpochDifficulty() external view returns (uint256);\n}\n" + }, + "contracts/bridge/MovingFunds.sol": { + "content": "// SPDX-License-Identifier: GPL-3.0-only\n\n// ██████████████ ▐████▌ ██████████████\n// ██████████████ ▐████▌ ██████████████\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ██████████████ ▐████▌ ██████████████\n// ██████████████ ▐████▌ ██████████████\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n\npragma solidity 0.8.17;\n\nimport {BTCUtils} from \"@keep-network/bitcoin-spv-sol/contracts/BTCUtils.sol\";\nimport {BytesLib} from \"@keep-network/bitcoin-spv-sol/contracts/BytesLib.sol\";\n\nimport \"./BitcoinTx.sol\";\nimport \"./BridgeState.sol\";\nimport \"./Redemption.sol\";\nimport \"./Wallets.sol\";\n\n/// @title Moving Bridge wallet funds\n/// @notice The library handles the logic for moving Bitcoin between Bridge\n/// wallets.\n/// @dev A wallet that failed a heartbeat, did not process requested redemption\n/// on time, or qualifies to be closed, begins the procedure of moving\n/// funds to other wallets in the Bridge. The wallet needs to commit to\n/// which other Live wallets it is moving the funds to and then, provide an\n/// SPV proof of moving funds to the previously committed wallets.\n/// Once the proof is submitted, all target wallets are supposed to\n/// sweep the received UTXOs with their own main UTXOs in order to\n/// update their BTC balances.\nlibrary MovingFunds {\n using BridgeState for BridgeState.Storage;\n using Wallets for BridgeState.Storage;\n using BitcoinTx for BridgeState.Storage;\n\n using BTCUtils for bytes;\n using BytesLib for bytes;\n\n /// @notice Represents temporary information needed during the processing\n /// of the moving funds Bitcoin transaction outputs. This structure\n /// is an internal one and should not be exported outside of the\n /// moving funds transaction processing code.\n /// @dev Allows to mitigate \"stack too deep\" errors on EVM.\n struct MovingFundsTxOutputsProcessingInfo {\n // 32-byte hash of the moving funds Bitcoin transaction.\n bytes32 movingFundsTxHash;\n // Output vector of the moving funds Bitcoin transaction. It is\n // assumed the vector's structure is valid so it must be validated\n // using e.g. `BTCUtils.validateVout` function before being used\n // during the processing. The validation is usually done as part\n // of the `BitcoinTx.validateProof` call that checks the SPV proof.\n bytes movingFundsTxOutputVector;\n // This struct doesn't contain `__gap` property as the structure is not\n // stored, it is used as a function's memory argument.\n }\n\n /// @notice Represents moved funds sweep request state.\n enum MovedFundsSweepRequestState {\n /// @dev The request is unknown to the Bridge.\n Unknown,\n /// @dev Request is pending and can become either processed or timed out.\n Pending,\n /// @dev Request was processed by the target wallet.\n Processed,\n /// @dev Request was not processed in the given time window and\n /// the timeout was reported.\n TimedOut\n }\n\n /// @notice Represents a moved funds sweep request. The request is\n /// registered in `submitMovingFundsProof` where we know funds\n /// have been moved to the target wallet and the only step left is\n /// to have the target wallet sweep them.\n struct MovedFundsSweepRequest {\n // 20-byte public key hash of the wallet supposed to sweep the UTXO\n // representing the received funds with their own main UTXO\n bytes20 walletPubKeyHash;\n // Value of the received funds.\n uint64 value;\n // UNIX timestamp the request was created at.\n // XXX: Unsigned 32-bit int unix seconds, will break February 7th 2106.\n uint32 createdAt;\n // The current state of the request.\n MovedFundsSweepRequestState state;\n // This struct doesn't contain `__gap` property as the structure is stored\n // in a mapping, mappings store values in different slots and they are\n // not contiguous with other values.\n }\n\n event MovingFundsCommitmentSubmitted(\n bytes20 indexed walletPubKeyHash,\n bytes20[] targetWallets,\n address submitter\n );\n\n event MovingFundsTimeoutReset(bytes20 indexed walletPubKeyHash);\n\n event MovingFundsCompleted(\n bytes20 indexed walletPubKeyHash,\n bytes32 movingFundsTxHash\n );\n\n event MovingFundsTimedOut(bytes20 indexed walletPubKeyHash);\n\n event MovingFundsBelowDustReported(bytes20 indexed walletPubKeyHash);\n\n event MovedFundsSwept(\n bytes20 indexed walletPubKeyHash,\n bytes32 sweepTxHash\n );\n\n event MovedFundsSweepTimedOut(\n bytes20 indexed walletPubKeyHash,\n bytes32 movingFundsTxHash,\n uint32 movingFundsTxOutputIndex\n );\n\n /// @notice Submits the moving funds target wallets commitment.\n /// Once all requirements are met, that function registers the\n /// target wallets commitment and opens the way for moving funds\n /// proof submission.\n /// @param walletPubKeyHash 20-byte public key hash of the source wallet.\n /// @param walletMainUtxo Data of the source wallet's main UTXO, as\n /// currently known on the Ethereum chain.\n /// @param walletMembersIDs Identifiers of the source wallet signing group\n /// members.\n /// @param walletMemberIndex Position of the caller in the source wallet\n /// signing group members list.\n /// @param targetWallets List of 20-byte public key hashes of the target\n /// wallets that the source wallet commits to move the funds to.\n /// @dev Requirements:\n /// - The source wallet must be in the MovingFunds state,\n /// - The source wallet must not have pending redemption requests,\n /// - The source wallet must not have pending moved funds sweep requests,\n /// - The source wallet must not have submitted its commitment already,\n /// - The expression `keccak256(abi.encode(walletMembersIDs))` must\n /// be exactly the same as the hash stored under `membersIdsHash`\n /// for the given source wallet in the ECDSA registry. Those IDs are\n /// not directly stored in the contract for gas efficiency purposes\n /// but they can be read from appropriate `DkgResultSubmitted`\n /// and `DkgResultApproved` events,\n /// - The `walletMemberIndex` must be in range [1, walletMembersIDs.length],\n /// - The caller must be the member of the source wallet signing group\n /// at the position indicated by `walletMemberIndex` parameter,\n /// - The `walletMainUtxo` components must point to the recent main\n /// UTXO of the source wallet, as currently known on the Ethereum\n /// chain,\n /// - Source wallet BTC balance must be greater than zero,\n /// - At least one Live wallet must exist in the system,\n /// - Submitted target wallets count must match the expected count\n /// `N = min(liveWalletsCount, ceil(walletBtcBalance / walletMaxBtcTransfer))`\n /// where `N > 0`,\n /// - Each target wallet must be not equal to the source wallet,\n /// - Each target wallet must follow the expected order i.e. all\n /// target wallets 20-byte public key hashes represented as numbers\n /// must form a strictly increasing sequence without duplicates,\n /// - Each target wallet must be in Live state.\n function submitMovingFundsCommitment(\n BridgeState.Storage storage self,\n bytes20 walletPubKeyHash,\n BitcoinTx.UTXO calldata walletMainUtxo,\n uint32[] calldata walletMembersIDs,\n uint256 walletMemberIndex,\n bytes20[] calldata targetWallets\n ) external {\n Wallets.Wallet storage wallet = self.registeredWallets[\n walletPubKeyHash\n ];\n\n require(\n wallet.state == Wallets.WalletState.MovingFunds,\n \"Source wallet must be in MovingFunds state\"\n );\n\n require(\n wallet.pendingRedemptionsValue == 0,\n \"Source wallet must handle all pending redemptions first\"\n );\n\n require(\n wallet.pendingMovedFundsSweepRequestsCount == 0,\n \"Source wallet must handle all pending moved funds sweep requests first\"\n );\n\n require(\n wallet.movingFundsTargetWalletsCommitmentHash == bytes32(0),\n \"Target wallets commitment already submitted\"\n );\n\n require(\n self.ecdsaWalletRegistry.isWalletMember(\n wallet.ecdsaWalletID,\n walletMembersIDs,\n msg.sender,\n walletMemberIndex\n ),\n \"Caller is not a member of the source wallet\"\n );\n\n uint64 walletBtcBalance = self.getWalletBtcBalance(\n walletPubKeyHash,\n walletMainUtxo\n );\n\n require(walletBtcBalance > 0, \"Wallet BTC balance is zero\");\n\n uint256 expectedTargetWalletsCount = Math.min(\n self.liveWalletsCount,\n Math.ceilDiv(walletBtcBalance, self.walletMaxBtcTransfer)\n );\n\n // This requirement fails only when `liveWalletsCount` is zero. In\n // that case, the system cannot accept the commitment and must provide\n // new wallets first. However, the wallet supposed to submit the\n // commitment can keep resetting the moving funds timeout until then.\n require(expectedTargetWalletsCount > 0, \"No target wallets available\");\n\n require(\n targetWallets.length == expectedTargetWalletsCount,\n \"Submitted target wallets count is other than expected\"\n );\n\n uint160 lastProcessedTargetWallet = 0;\n\n for (uint256 i = 0; i < targetWallets.length; i++) {\n bytes20 targetWallet = targetWallets[i];\n\n require(\n targetWallet != walletPubKeyHash,\n \"Submitted target wallet cannot be equal to the source wallet\"\n );\n\n require(\n uint160(targetWallet) > lastProcessedTargetWallet,\n \"Submitted target wallet breaks the expected order\"\n );\n\n require(\n self.registeredWallets[targetWallet].state ==\n Wallets.WalletState.Live,\n \"Submitted target wallet must be in Live state\"\n );\n\n lastProcessedTargetWallet = uint160(targetWallet);\n }\n\n wallet.movingFundsTargetWalletsCommitmentHash = keccak256(\n abi.encodePacked(targetWallets)\n );\n\n emit MovingFundsCommitmentSubmitted(\n walletPubKeyHash,\n targetWallets,\n msg.sender\n );\n }\n\n /// @notice Resets the moving funds timeout for the given wallet if the\n /// target wallet commitment cannot be submitted due to a lack\n /// of live wallets in the system.\n /// @param walletPubKeyHash 20-byte public key hash of the moving funds wallet\n /// @dev Requirements:\n /// - The wallet must be in the MovingFunds state,\n /// - The target wallets commitment must not be already submitted for\n /// the given moving funds wallet,\n /// - Live wallets count must be zero,\n /// - The moving funds timeout reset delay must be elapsed.\n function resetMovingFundsTimeout(\n BridgeState.Storage storage self,\n bytes20 walletPubKeyHash\n ) external {\n Wallets.Wallet storage wallet = self.registeredWallets[\n walletPubKeyHash\n ];\n\n require(\n wallet.state == Wallets.WalletState.MovingFunds,\n \"Wallet must be in MovingFunds state\"\n );\n\n // If the moving funds wallet already submitted their target wallets\n // commitment, there is no point to reset the timeout since the\n // wallet can make the BTC transaction and submit the proof.\n require(\n wallet.movingFundsTargetWalletsCommitmentHash == bytes32(0),\n \"Target wallets commitment already submitted\"\n );\n\n require(self.liveWalletsCount == 0, \"Live wallets count must be zero\");\n\n require(\n /* solhint-disable-next-line not-rely-on-time */\n block.timestamp >\n wallet.movingFundsRequestedAt +\n self.movingFundsTimeoutResetDelay,\n \"Moving funds timeout cannot be reset yet\"\n );\n\n /* solhint-disable-next-line not-rely-on-time */\n wallet.movingFundsRequestedAt = uint32(block.timestamp);\n\n emit MovingFundsTimeoutReset(walletPubKeyHash);\n }\n\n /// @notice Used by the wallet to prove the BTC moving funds transaction\n /// and to make the necessary state changes. Moving funds is only\n /// accepted if it satisfies SPV proof.\n ///\n /// The function validates the moving funds transaction structure\n /// by checking if it actually spends the main UTXO of the declared\n /// wallet and locks the value on the pre-committed target wallets\n /// using a reasonable transaction fee. If all preconditions are\n /// met, this functions closes the source wallet.\n ///\n /// It is possible to prove the given moving funds transaction only\n /// one time.\n /// @param movingFundsTx Bitcoin moving funds transaction data.\n /// @param movingFundsProof Bitcoin moving funds proof data.\n /// @param mainUtxo Data of the wallet's main UTXO, as currently known on\n /// the Ethereum chain.\n /// @param walletPubKeyHash 20-byte public key hash (computed using Bitcoin\n /// HASH160 over the compressed ECDSA public key) of the wallet\n /// which performed the moving funds transaction.\n /// @dev Requirements:\n /// - `movingFundsTx` components must match the expected structure. See\n /// `BitcoinTx.Info` docs for reference. Their values must exactly\n /// correspond to appropriate Bitcoin transaction fields to produce\n /// a provable transaction hash,\n /// - The `movingFundsTx` should represent a Bitcoin transaction with\n /// exactly 1 input that refers to the wallet's main UTXO. That\n /// transaction should have 1..n outputs corresponding to the\n /// pre-committed target wallets. Outputs must be ordered in the\n /// same way as their corresponding target wallets are ordered\n /// within the target wallets commitment,\n /// - `movingFundsProof` components must match the expected structure.\n /// See `BitcoinTx.Proof` docs for reference. The `bitcoinHeaders`\n /// field must contain a valid number of block headers, not less\n /// than the `txProofDifficultyFactor` contract constant,\n /// - `mainUtxo` components must point to the recent main UTXO\n /// of the given wallet, as currently known on the Ethereum chain.\n /// Additionally, the recent main UTXO on Ethereum must be set,\n /// - `walletPubKeyHash` must be connected with the main UTXO used\n /// as transaction single input,\n /// - The wallet that `walletPubKeyHash` points to must be in the\n /// MovingFunds state,\n /// - The target wallets commitment must be submitted by the wallet\n /// that `walletPubKeyHash` points to,\n /// - The total Bitcoin transaction fee must be lesser or equal\n /// to `movingFundsTxMaxTotalFee` governable parameter.\n function submitMovingFundsProof(\n BridgeState.Storage storage self,\n BitcoinTx.Info calldata movingFundsTx,\n BitcoinTx.Proof calldata movingFundsProof,\n BitcoinTx.UTXO calldata mainUtxo,\n bytes20 walletPubKeyHash\n ) external {\n // Wallet state is validated in `notifyWalletFundsMoved`.\n\n // The actual transaction proof is performed here. After that point, we\n // can assume the transaction happened on Bitcoin chain and has\n // a sufficient number of confirmations as determined by\n // `txProofDifficultyFactor` constant.\n bytes32 movingFundsTxHash = self.validateProof(\n movingFundsTx,\n movingFundsProof\n );\n\n // Assert that main UTXO for passed wallet exists in storage.\n bytes32 mainUtxoHash = self\n .registeredWallets[walletPubKeyHash]\n .mainUtxoHash;\n require(mainUtxoHash != bytes32(0), \"No main UTXO for given wallet\");\n\n // Assert that passed main UTXO parameter is the same as in storage and\n // can be used for further processing.\n require(\n keccak256(\n abi.encodePacked(\n mainUtxo.txHash,\n mainUtxo.txOutputIndex,\n mainUtxo.txOutputValue\n )\n ) == mainUtxoHash,\n \"Invalid main UTXO data\"\n );\n\n // Process the moving funds transaction input. Specifically, check if\n // it refers to the expected wallet's main UTXO.\n OutboundTx.processWalletOutboundTxInput(\n self,\n movingFundsTx.inputVector,\n mainUtxo\n );\n\n (\n bytes32 targetWalletsHash,\n uint256 outputsTotalValue\n ) = processMovingFundsTxOutputs(\n self,\n MovingFundsTxOutputsProcessingInfo(\n movingFundsTxHash,\n movingFundsTx.outputVector\n )\n );\n\n require(\n mainUtxo.txOutputValue - outputsTotalValue <=\n self.movingFundsTxMaxTotalFee,\n \"Transaction fee is too high\"\n );\n\n self.notifyWalletFundsMoved(walletPubKeyHash, targetWalletsHash);\n // slither-disable-next-line reentrancy-events\n emit MovingFundsCompleted(walletPubKeyHash, movingFundsTxHash);\n }\n\n /// @notice Processes the moving funds Bitcoin transaction output vector\n /// and extracts information required for further processing.\n /// @param processInfo Processing info containing the moving funds tx\n /// hash and output vector.\n /// @return targetWalletsHash keccak256 hash over the list of actual\n /// target wallets used in the transaction.\n /// @return outputsTotalValue Sum of all outputs values.\n /// @dev Requirements:\n /// - The `movingFundsTxOutputVector` must be parseable, i.e. must\n /// be validated by the caller as stated in their parameter doc,\n /// - Each output must refer to a 20-byte public key hash,\n /// - The total outputs value must be evenly divided over all outputs.\n function processMovingFundsTxOutputs(\n BridgeState.Storage storage self,\n MovingFundsTxOutputsProcessingInfo memory processInfo\n ) internal returns (bytes32 targetWalletsHash, uint256 outputsTotalValue) {\n // Determining the total number of Bitcoin transaction outputs in\n // the same way as for number of inputs. See `BitcoinTx.outputVector`\n // docs for more details.\n (\n uint256 outputsCompactSizeUintLength,\n uint256 outputsCount\n ) = processInfo.movingFundsTxOutputVector.parseVarInt();\n\n // To determine the first output starting index, we must jump over\n // the compactSize uint which prepends the output vector. One byte\n // must be added because `BtcUtils.parseVarInt` does not include\n // compactSize uint tag in the returned length.\n //\n // For >= 0 && <= 252, `BTCUtils.determineVarIntDataLengthAt`\n // returns `0`, so we jump over one byte of compactSize uint.\n //\n // For >= 253 && <= 0xffff there is `0xfd` tag,\n // `BTCUtils.determineVarIntDataLengthAt` returns `2` (no\n // tag byte included) so we need to jump over 1+2 bytes of\n // compactSize uint.\n //\n // Please refer `BTCUtils` library and compactSize uint\n // docs in `BitcoinTx` library for more details.\n uint256 outputStartingIndex = 1 + outputsCompactSizeUintLength;\n\n bytes20[] memory targetWallets = new bytes20[](outputsCount);\n uint64[] memory outputsValues = new uint64[](outputsCount);\n\n // Outputs processing loop. Note that the `outputIndex` must be\n // `uint32` to build proper `movedFundsSweepRequests` keys.\n for (\n uint32 outputIndex = 0;\n outputIndex < outputsCount;\n outputIndex++\n ) {\n uint256 outputLength = processInfo\n .movingFundsTxOutputVector\n .determineOutputLengthAt(outputStartingIndex);\n\n bytes memory output = processInfo.movingFundsTxOutputVector.slice(\n outputStartingIndex,\n outputLength\n );\n\n bytes20 targetWalletPubKeyHash = self.extractPubKeyHash(output);\n\n // Add the wallet public key hash to the list that will be used\n // to build the result list hash. There is no need to check if\n // given output is a change here because the actual target wallet\n // list must be exactly the same as the pre-committed target wallet\n // list which is guaranteed to be valid.\n targetWallets[outputIndex] = targetWalletPubKeyHash;\n\n // Extract the value from given output.\n outputsValues[outputIndex] = output.extractValue();\n outputsTotalValue += outputsValues[outputIndex];\n\n // Register a moved funds sweep request that must be handled\n // by the target wallet. The target wallet must sweep the\n // received funds with their own main UTXO in order to update\n // their BTC balance. Worth noting there is no need to check\n // if the sweep request already exists in the system because\n // the moving funds wallet is moved to the Closing state after\n // submitting the moving funds proof so there is no possibility\n // to submit the proof again and register the sweep request twice.\n self.movedFundsSweepRequests[\n uint256(\n keccak256(\n abi.encodePacked(\n processInfo.movingFundsTxHash,\n outputIndex\n )\n )\n )\n ] = MovedFundsSweepRequest(\n targetWalletPubKeyHash,\n outputsValues[outputIndex],\n /* solhint-disable-next-line not-rely-on-time */\n uint32(block.timestamp),\n MovedFundsSweepRequestState.Pending\n );\n // We added a new moved funds sweep request for the target wallet\n // so we must increment their request counter.\n self\n .registeredWallets[targetWalletPubKeyHash]\n .pendingMovedFundsSweepRequestsCount++;\n\n // Make the `outputStartingIndex` pointing to the next output by\n // increasing it by current output's length.\n outputStartingIndex += outputLength;\n }\n\n // Compute the indivisible remainder that remains after dividing the\n // outputs total value over all outputs evenly.\n uint256 outputsTotalValueRemainder = outputsTotalValue % outputsCount;\n // Compute the minimum allowed output value by dividing the outputs\n // total value (reduced by the remainder) by the number of outputs.\n uint256 minOutputValue = (outputsTotalValue -\n outputsTotalValueRemainder) / outputsCount;\n // Maximum possible value is the minimum value with the remainder included.\n uint256 maxOutputValue = minOutputValue + outputsTotalValueRemainder;\n\n for (uint256 i = 0; i < outputsCount; i++) {\n require(\n minOutputValue <= outputsValues[i] &&\n outputsValues[i] <= maxOutputValue,\n \"Transaction amount is not distributed evenly\"\n );\n }\n\n targetWalletsHash = keccak256(abi.encodePacked(targetWallets));\n\n return (targetWalletsHash, outputsTotalValue);\n }\n\n /// @notice Notifies about a timed out moving funds process. Terminates\n /// the wallet and slashes signing group members as a result.\n /// @param walletPubKeyHash 20-byte public key hash of the wallet.\n /// @param walletMembersIDs Identifiers of the wallet signing group members.\n /// @dev Requirements:\n /// - The wallet must be in the MovingFunds state,\n /// - The moving funds timeout must be actually exceeded,\n /// - The expression `keccak256(abi.encode(walletMembersIDs))` must\n /// be exactly the same as the hash stored under `membersIdsHash`\n /// for the given `walletID`. Those IDs are not directly stored\n /// in the contract for gas efficiency purposes but they can be\n /// read from appropriate `DkgResultSubmitted` and `DkgResultApproved`\n /// events of the `WalletRegistry` contract.\n function notifyMovingFundsTimeout(\n BridgeState.Storage storage self,\n bytes20 walletPubKeyHash,\n uint32[] calldata walletMembersIDs\n ) external {\n // Wallet state is validated in `notifyWalletMovingFundsTimeout`.\n\n uint32 movingFundsRequestedAt = self\n .registeredWallets[walletPubKeyHash]\n .movingFundsRequestedAt;\n\n require(\n /* solhint-disable-next-line not-rely-on-time */\n block.timestamp > movingFundsRequestedAt + self.movingFundsTimeout,\n \"Moving funds has not timed out yet\"\n );\n\n self.notifyWalletMovingFundsTimeout(walletPubKeyHash, walletMembersIDs);\n\n // slither-disable-next-line reentrancy-events\n emit MovingFundsTimedOut(walletPubKeyHash);\n }\n\n /// @notice Notifies about a moving funds wallet whose BTC balance is\n /// below the moving funds dust threshold. Ends the moving funds\n /// process and begins wallet closing immediately.\n /// @param walletPubKeyHash 20-byte public key hash of the wallet.\n /// @param mainUtxo Data of the wallet's main UTXO, as currently known\n /// on the Ethereum chain.\n /// @dev Requirements:\n /// - The wallet must be in the MovingFunds state,\n /// - The `mainUtxo` components must point to the recent main UTXO\n /// of the given wallet, as currently known on the Ethereum chain.\n /// If the wallet has no main UTXO, this parameter can be empty as it\n /// is ignored,\n /// - The wallet BTC balance must be below the moving funds threshold.\n function notifyMovingFundsBelowDust(\n BridgeState.Storage storage self,\n bytes20 walletPubKeyHash,\n BitcoinTx.UTXO calldata mainUtxo\n ) external {\n // Wallet state is validated in `notifyWalletMovingFundsBelowDust`.\n\n uint64 walletBtcBalance = self.getWalletBtcBalance(\n walletPubKeyHash,\n mainUtxo\n );\n\n require(\n walletBtcBalance < self.movingFundsDustThreshold,\n \"Wallet BTC balance must be below the moving funds dust threshold\"\n );\n\n self.notifyWalletMovingFundsBelowDust(walletPubKeyHash);\n\n // slither-disable-next-line reentrancy-events\n emit MovingFundsBelowDustReported(walletPubKeyHash);\n }\n\n /// @notice Used by the wallet to prove the BTC moved funds sweep\n /// transaction and to make the necessary state changes. Moved\n /// funds sweep is only accepted if it satisfies SPV proof.\n ///\n /// The function validates the sweep transaction structure by\n /// checking if it actually spends the moved funds UTXO and the\n /// sweeping wallet's main UTXO (optionally), and if it locks the\n /// value on the sweeping wallet's 20-byte public key hash using a\n /// reasonable transaction fee. If all preconditions are\n /// met, this function updates the sweeping wallet main UTXO, thus\n /// their BTC balance.\n ///\n /// It is possible to prove the given sweep transaction only\n /// one time.\n /// @param sweepTx Bitcoin sweep funds transaction data.\n /// @param sweepProof Bitcoin sweep funds proof data.\n /// @param mainUtxo Data of the sweeping wallet's main UTXO, as currently\n /// known on the Ethereum chain.\n /// @dev Requirements:\n /// - `sweepTx` components must match the expected structure. See\n /// `BitcoinTx.Info` docs for reference. Their values must exactly\n /// correspond to appropriate Bitcoin transaction fields to produce\n /// a provable transaction hash,\n /// - The `sweepTx` should represent a Bitcoin transaction with\n /// the first input pointing to a wallet's sweep Pending request and,\n /// optionally, the second input pointing to the wallet's main UTXO,\n /// if the sweeping wallet has a main UTXO set. There should be only\n /// one output locking funds on the sweeping wallet 20-byte public\n /// key hash,\n /// - `sweepProof` components must match the expected structure.\n /// See `BitcoinTx.Proof` docs for reference. The `bitcoinHeaders`\n /// field must contain a valid number of block headers, not less\n /// than the `txProofDifficultyFactor` contract constant,\n /// - `mainUtxo` components must point to the recent main UTXO\n /// of the sweeping wallet, as currently known on the Ethereum chain.\n /// If there is no main UTXO, this parameter is ignored,\n /// - The sweeping wallet must be in the Live or MovingFunds state,\n /// - The total Bitcoin transaction fee must be lesser or equal\n /// to `movedFundsSweepTxMaxTotalFee` governable parameter.\n function submitMovedFundsSweepProof(\n BridgeState.Storage storage self,\n BitcoinTx.Info calldata sweepTx,\n BitcoinTx.Proof calldata sweepProof,\n BitcoinTx.UTXO calldata mainUtxo\n ) external {\n // Wallet state validation is performed in the\n // `resolveMovedFundsSweepingWallet` function.\n\n // The actual transaction proof is performed here. After that point, we\n // can assume the transaction happened on Bitcoin chain and has\n // a sufficient number of confirmations as determined by\n // `txProofDifficultyFactor` constant.\n bytes32 sweepTxHash = self.validateProof(sweepTx, sweepProof);\n\n (\n bytes20 walletPubKeyHash,\n uint64 sweepTxOutputValue\n ) = processMovedFundsSweepTxOutput(self, sweepTx.outputVector);\n\n (\n Wallets.Wallet storage wallet,\n BitcoinTx.UTXO memory resolvedMainUtxo\n ) = resolveMovedFundsSweepingWallet(self, walletPubKeyHash, mainUtxo);\n\n uint256 sweepTxInputsTotalValue = processMovedFundsSweepTxInputs(\n self,\n sweepTx.inputVector,\n resolvedMainUtxo,\n walletPubKeyHash\n );\n\n require(\n sweepTxInputsTotalValue - sweepTxOutputValue <=\n self.movedFundsSweepTxMaxTotalFee,\n \"Transaction fee is too high\"\n );\n\n // Use the sweep transaction output as the new sweeping wallet's main UTXO.\n // Transaction output index is always 0 as sweep transaction always\n // contains only one output.\n wallet.mainUtxoHash = keccak256(\n abi.encodePacked(sweepTxHash, uint32(0), sweepTxOutputValue)\n );\n\n // slither-disable-next-line reentrancy-events\n emit MovedFundsSwept(walletPubKeyHash, sweepTxHash);\n }\n\n /// @notice Processes the Bitcoin moved funds sweep transaction output vector\n /// by extracting the single output and using it to gain additional\n /// information required for further processing (e.g. value and\n /// wallet public key hash).\n /// @param sweepTxOutputVector Bitcoin moved funds sweep transaction output\n /// vector.\n /// This function assumes vector's structure is valid so it must be\n /// validated using e.g. `BTCUtils.validateVout` function before\n /// it is passed here.\n /// @return walletPubKeyHash 20-byte wallet public key hash.\n /// @return value 8-byte moved funds sweep transaction output value.\n /// @dev Requirements:\n /// - Output vector must contain only one output,\n /// - The single output must be of P2PKH or P2WPKH type and lock the\n /// funds on a 20-byte public key hash.\n function processMovedFundsSweepTxOutput(\n BridgeState.Storage storage self,\n bytes memory sweepTxOutputVector\n ) internal view returns (bytes20 walletPubKeyHash, uint64 value) {\n // To determine the total number of sweep transaction outputs, we need to\n // parse the compactSize uint (VarInt) the output vector is prepended by.\n // That compactSize uint encodes the number of vector elements using the\n // format presented in:\n // https://developer.bitcoin.org/reference/transactions.html#compactsize-unsigned-integers\n // We don't need asserting the compactSize uint is parseable since it\n // was already checked during `validateVout` validation performed as\n // part of the `BitcoinTx.validateProof` call.\n // See `BitcoinTx.outputVector` docs for more details.\n (, uint256 outputsCount) = sweepTxOutputVector.parseVarInt();\n require(\n outputsCount == 1,\n \"Moved funds sweep transaction must have a single output\"\n );\n\n bytes memory output = sweepTxOutputVector.extractOutputAtIndex(0);\n walletPubKeyHash = self.extractPubKeyHash(output);\n value = output.extractValue();\n\n return (walletPubKeyHash, value);\n }\n\n /// @notice Resolves sweeping wallet based on the provided wallet public key\n /// hash. Validates the wallet state and current main UTXO, as\n /// currently known on the Ethereum chain.\n /// @param walletPubKeyHash public key hash of the wallet proving the sweep\n /// Bitcoin transaction.\n /// @param mainUtxo Data of the wallet's main UTXO, as currently known on\n /// the Ethereum chain. If no main UTXO exists for the given wallet,\n /// this parameter is ignored.\n /// @return wallet Data of the sweeping wallet.\n /// @return resolvedMainUtxo The actual main UTXO of the sweeping wallet\n /// resolved by cross-checking the `mainUtxo` parameter with\n /// the chain state. If the validation went well, this is the\n /// plain-text main UTXO corresponding to the `wallet.mainUtxoHash`.\n /// @dev Requirements:\n /// - Sweeping wallet must be either in Live or MovingFunds state,\n /// - If the main UTXO of the sweeping wallet exists in the storage,\n /// the passed `mainUTXO` parameter must be equal to the stored one.\n function resolveMovedFundsSweepingWallet(\n BridgeState.Storage storage self,\n bytes20 walletPubKeyHash,\n BitcoinTx.UTXO calldata mainUtxo\n )\n internal\n view\n returns (\n Wallets.Wallet storage wallet,\n BitcoinTx.UTXO memory resolvedMainUtxo\n )\n {\n wallet = self.registeredWallets[walletPubKeyHash];\n\n Wallets.WalletState walletState = wallet.state;\n require(\n walletState == Wallets.WalletState.Live ||\n walletState == Wallets.WalletState.MovingFunds,\n \"Wallet must be in Live or MovingFunds state\"\n );\n\n // Check if the main UTXO for given wallet exists. If so, validate\n // passed main UTXO data against the stored hash and use them for\n // further processing. If no main UTXO exists, use empty data.\n resolvedMainUtxo = BitcoinTx.UTXO(bytes32(0), 0, 0);\n bytes32 mainUtxoHash = wallet.mainUtxoHash;\n if (mainUtxoHash != bytes32(0)) {\n require(\n keccak256(\n abi.encodePacked(\n mainUtxo.txHash,\n mainUtxo.txOutputIndex,\n mainUtxo.txOutputValue\n )\n ) == mainUtxoHash,\n \"Invalid main UTXO data\"\n );\n resolvedMainUtxo = mainUtxo;\n }\n }\n\n /// @notice Processes the Bitcoin moved funds sweep transaction input vector.\n /// It extracts the first input and tries to match it with one of\n /// the moved funds sweep requests targeting the sweeping wallet.\n /// If the sweep request is an existing Pending request, this\n /// function marks it as Processed. If the sweeping wallet has a\n /// main UTXO, this function extracts the second input, makes sure\n /// it refers to the wallet main UTXO, and marks that main UTXO as\n /// correctly spent.\n /// @param sweepTxInputVector Bitcoin moved funds sweep transaction input vector.\n /// This function assumes vector's structure is valid so it must be\n /// validated using e.g. `BTCUtils.validateVin` function before\n /// it is passed here.\n /// @param mainUtxo Data of the sweeping wallet's main UTXO. If no main UTXO\n /// exists for the given the wallet, this parameter's fields should\n /// be zeroed to bypass the main UTXO validation.\n /// @param walletPubKeyHash 20-byte public key hash of the sweeping wallet.\n /// @return inputsTotalValue Total inputs value sum.\n /// @dev Requirements:\n /// - The input vector must consist of one mandatory and one optional\n /// input,\n /// - The mandatory input must be the first input in the vector,\n /// - The mandatory input must point to a Pending moved funds sweep\n /// request that is targeted to the sweeping wallet,\n /// - The optional output must be the second input in the vector,\n /// - The optional input is required if the sweeping wallet has a\n /// main UTXO (i.e. the `mainUtxo` is not zeroed). In that case,\n /// that input must point the the sweeping wallet main UTXO.\n function processMovedFundsSweepTxInputs(\n BridgeState.Storage storage self,\n bytes memory sweepTxInputVector,\n BitcoinTx.UTXO memory mainUtxo,\n bytes20 walletPubKeyHash\n ) internal returns (uint256 inputsTotalValue) {\n // To determine the total number of Bitcoin transaction inputs,\n // we need to parse the compactSize uint (VarInt) the input vector is\n // prepended by. That compactSize uint encodes the number of vector\n // elements using the format presented in:\n // https://developer.bitcoin.org/reference/transactions.html#compactsize-unsigned-integers\n // We don't need asserting the compactSize uint is parseable since it\n // was already checked during `validateVin` validation performed as\n // part of the `BitcoinTx.validateProof` call.\n // See `BitcoinTx.inputVector` docs for more details.\n (\n uint256 inputsCompactSizeUintLength,\n uint256 inputsCount\n ) = sweepTxInputVector.parseVarInt();\n\n // To determine the first input starting index, we must jump over\n // the compactSize uint which prepends the input vector. One byte\n // must be added because `BtcUtils.parseVarInt` does not include\n // compactSize uint tag in the returned length.\n //\n // For >= 0 && <= 252, `BTCUtils.determineVarIntDataLengthAt`\n // returns `0`, so we jump over one byte of compactSize uint.\n //\n // For >= 253 && <= 0xffff there is `0xfd` tag,\n // `BTCUtils.determineVarIntDataLengthAt` returns `2` (no\n // tag byte included) so we need to jump over 1+2 bytes of\n // compactSize uint.\n //\n // Please refer `BTCUtils` library and compactSize uint\n // docs in `BitcoinTx` library for more details.\n uint256 inputStartingIndex = 1 + inputsCompactSizeUintLength;\n\n // We always expect the first input to be the swept UTXO. Additionally,\n // if the sweeping wallet has a main UTXO, that main UTXO should be\n // pointed by the second input.\n require(\n inputsCount == (mainUtxo.txHash != bytes32(0) ? 2 : 1),\n \"Moved funds sweep transaction must have a proper inputs count\"\n );\n\n // Parse the first input and extract its outpoint tx hash and index.\n (\n bytes32 firstInputOutpointTxHash,\n uint32 firstInputOutpointIndex,\n uint256 firstInputLength\n ) = parseMovedFundsSweepTxInputAt(\n sweepTxInputVector,\n inputStartingIndex\n );\n\n // Build the request key and fetch the corresponding moved funds sweep\n // request from contract storage.\n MovedFundsSweepRequest storage sweepRequest = self\n .movedFundsSweepRequests[\n uint256(\n keccak256(\n abi.encodePacked(\n firstInputOutpointTxHash,\n firstInputOutpointIndex\n )\n )\n )\n ];\n\n require(\n sweepRequest.state == MovedFundsSweepRequestState.Pending,\n \"Sweep request must be in Pending state\"\n );\n // We must check if the wallet extracted from the moved funds sweep\n // transaction output is truly the owner of the sweep request connected\n // with the swept UTXO. This is needed to prevent a case when a wallet\n // handles its own sweep request but locks the funds on another\n // wallet public key hash.\n require(\n sweepRequest.walletPubKeyHash == walletPubKeyHash,\n \"Sweep request belongs to another wallet\"\n );\n // If the validation passed, the sweep request must be marked as\n // processed and its value should be counted into the total inputs\n // value sum.\n sweepRequest.state = MovedFundsSweepRequestState.Processed;\n inputsTotalValue += sweepRequest.value;\n\n self\n .registeredWallets[walletPubKeyHash]\n .pendingMovedFundsSweepRequestsCount--;\n\n // If the main UTXO for the sweeping wallet exists, it must be processed.\n if (mainUtxo.txHash != bytes32(0)) {\n // The second input is supposed to point to that sweeping wallet\n // main UTXO. We need to parse that input.\n (\n bytes32 secondInputOutpointTxHash,\n uint32 secondInputOutpointIndex,\n\n ) = parseMovedFundsSweepTxInputAt(\n sweepTxInputVector,\n inputStartingIndex + firstInputLength\n );\n // Make sure the second input refers to the sweeping wallet main UTXO.\n require(\n mainUtxo.txHash == secondInputOutpointTxHash &&\n mainUtxo.txOutputIndex == secondInputOutpointIndex,\n \"Second input must point to the wallet's main UTXO\"\n );\n\n // If the validation passed, count the main UTXO value into the\n // total inputs value sum.\n inputsTotalValue += mainUtxo.txOutputValue;\n\n // Main UTXO used as an input, mark it as spent. This is needed\n // to defend against fraud challenges referring to this main UTXO.\n self.spentMainUTXOs[\n uint256(\n keccak256(\n abi.encodePacked(\n secondInputOutpointTxHash,\n secondInputOutpointIndex\n )\n )\n )\n ] = true;\n }\n\n return inputsTotalValue;\n }\n\n /// @notice Parses a Bitcoin transaction input starting at the given index.\n /// @param inputVector Bitcoin transaction input vector.\n /// @param inputStartingIndex Index the given input starts at.\n /// @return outpointTxHash 32-byte hash of the Bitcoin transaction which is\n /// pointed in the given input's outpoint.\n /// @return outpointIndex 4-byte index of the Bitcoin transaction output\n /// which is pointed in the given input's outpoint.\n /// @return inputLength Byte length of the given input.\n /// @dev This function assumes vector's structure is valid so it must be\n /// validated using e.g. `BTCUtils.validateVin` function before it\n /// is passed here.\n function parseMovedFundsSweepTxInputAt(\n bytes memory inputVector,\n uint256 inputStartingIndex\n )\n internal\n pure\n returns (\n bytes32 outpointTxHash,\n uint32 outpointIndex,\n uint256 inputLength\n )\n {\n outpointTxHash = inputVector.extractInputTxIdLeAt(inputStartingIndex);\n\n outpointIndex = BTCUtils.reverseUint32(\n uint32(inputVector.extractTxIndexLeAt(inputStartingIndex))\n );\n\n inputLength = inputVector.determineInputLengthAt(inputStartingIndex);\n\n return (outpointTxHash, outpointIndex, inputLength);\n }\n\n /// @notice Notifies about a timed out moved funds sweep process. If the\n /// wallet is not terminated yet, that function terminates\n /// the wallet and slashes signing group members as a result.\n /// Marks the given sweep request as TimedOut.\n /// @param movingFundsTxHash 32-byte hash of the moving funds transaction\n /// that caused the sweep request to be created.\n /// @param movingFundsTxOutputIndex Index of the moving funds transaction\n /// output that is subject of the sweep request.\n /// @param walletMembersIDs Identifiers of the wallet signing group members.\n /// @dev Requirements:\n /// - The moved funds sweep request must be in the Pending state,\n /// - The moved funds sweep timeout must be actually exceeded,\n /// - The wallet must be either in the Live or MovingFunds or\n /// Terminated state,,\n /// - The expression `keccak256(abi.encode(walletMembersIDs))` must\n /// be exactly the same as the hash stored under `membersIdsHash`\n /// for the given `walletID`. Those IDs are not directly stored\n /// in the contract for gas efficiency purposes but they can be\n /// read from appropriate `DkgResultSubmitted` and `DkgResultApproved`\n /// events of the `WalletRegistry` contract.\n function notifyMovedFundsSweepTimeout(\n BridgeState.Storage storage self,\n bytes32 movingFundsTxHash,\n uint32 movingFundsTxOutputIndex,\n uint32[] calldata walletMembersIDs\n ) external {\n // Wallet state is validated in `notifyWalletMovedFundsSweepTimeout`.\n\n MovedFundsSweepRequest storage sweepRequest = self\n .movedFundsSweepRequests[\n uint256(\n keccak256(\n abi.encodePacked(\n movingFundsTxHash,\n movingFundsTxOutputIndex\n )\n )\n )\n ];\n\n require(\n sweepRequest.state == MovedFundsSweepRequestState.Pending,\n \"Sweep request must be in Pending state\"\n );\n\n require(\n /* solhint-disable-next-line not-rely-on-time */\n block.timestamp >\n sweepRequest.createdAt + self.movedFundsSweepTimeout,\n \"Sweep request has not timed out yet\"\n );\n\n bytes20 walletPubKeyHash = sweepRequest.walletPubKeyHash;\n\n self.notifyWalletMovedFundsSweepTimeout(\n walletPubKeyHash,\n walletMembersIDs\n );\n\n Wallets.Wallet storage wallet = self.registeredWallets[\n walletPubKeyHash\n ];\n sweepRequest.state = MovedFundsSweepRequestState.TimedOut;\n wallet.pendingMovedFundsSweepRequestsCount--;\n\n // slither-disable-next-line reentrancy-events\n emit MovedFundsSweepTimedOut(\n walletPubKeyHash,\n movingFundsTxHash,\n movingFundsTxOutputIndex\n );\n }\n}\n" + }, + "contracts/bridge/Redemption.sol": { + "content": "// SPDX-License-Identifier: GPL-3.0-only\n\n// ██████████████ ▐████▌ ██████████████\n// ██████████████ ▐████▌ ██████████████\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ██████████████ ▐████▌ ██████████████\n// ██████████████ ▐████▌ ██████████████\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n\npragma solidity 0.8.17;\n\nimport {BTCUtils} from \"@keep-network/bitcoin-spv-sol/contracts/BTCUtils.sol\";\nimport {BytesLib} from \"@keep-network/bitcoin-spv-sol/contracts/BytesLib.sol\";\n\nimport \"./BitcoinTx.sol\";\nimport \"./BridgeState.sol\";\nimport \"./Wallets.sol\";\n\nimport \"../bank/Bank.sol\";\n\n/// @notice Aggregates functions common to the redemption transaction proof\n/// validation and to the moving funds transaction proof validation.\nlibrary OutboundTx {\n using BTCUtils for bytes;\n\n /// @notice Checks whether an outbound Bitcoin transaction performed from\n /// the given wallet has an input vector that contains a single\n /// input referring to the wallet's main UTXO. Marks that main UTXO\n /// as correctly spent if the validation succeeds. Reverts otherwise.\n /// There are two outbound transactions from a wallet possible: a\n /// redemption transaction or a moving funds to another wallet\n /// transaction.\n /// @param walletOutboundTxInputVector Bitcoin outbound transaction's input\n /// vector. This function assumes vector's structure is valid so it\n /// must be validated using e.g. `BTCUtils.validateVin` function\n /// before it is passed here.\n /// @param mainUtxo Data of the wallet's main UTXO, as currently known on\n /// the Ethereum chain.\n function processWalletOutboundTxInput(\n BridgeState.Storage storage self,\n bytes memory walletOutboundTxInputVector,\n BitcoinTx.UTXO calldata mainUtxo\n ) internal {\n // Assert that the single outbound transaction input actually\n // refers to the wallet's main UTXO.\n (\n bytes32 outpointTxHash,\n uint32 outpointIndex\n ) = parseWalletOutboundTxInput(walletOutboundTxInputVector);\n require(\n mainUtxo.txHash == outpointTxHash &&\n mainUtxo.txOutputIndex == outpointIndex,\n \"Outbound transaction input must point to the wallet's main UTXO\"\n );\n\n // Main UTXO used as an input, mark it as spent.\n self.spentMainUTXOs[\n uint256(\n keccak256(\n abi.encodePacked(mainUtxo.txHash, mainUtxo.txOutputIndex)\n )\n )\n ] = true;\n }\n\n /// @notice Parses the input vector of an outbound Bitcoin transaction\n /// performed from the given wallet. It extracts the single input\n /// then the transaction hash and output index from its outpoint.\n /// There are two outbound transactions from a wallet possible: a\n /// redemption transaction or a moving funds to another wallet\n /// transaction.\n /// @param walletOutboundTxInputVector Bitcoin outbound transaction input\n /// vector. This function assumes vector's structure is valid so it\n /// must be validated using e.g. `BTCUtils.validateVin` function\n /// before it is passed here.\n /// @return outpointTxHash 32-byte hash of the Bitcoin transaction which is\n /// pointed in the input's outpoint.\n /// @return outpointIndex 4-byte index of the Bitcoin transaction output\n /// which is pointed in the input's outpoint.\n function parseWalletOutboundTxInput(\n bytes memory walletOutboundTxInputVector\n ) internal pure returns (bytes32 outpointTxHash, uint32 outpointIndex) {\n // To determine the total number of Bitcoin transaction inputs,\n // we need to parse the compactSize uint (VarInt) the input vector is\n // prepended by. That compactSize uint encodes the number of vector\n // elements using the format presented in:\n // https://developer.bitcoin.org/reference/transactions.html#compactsize-unsigned-integers\n // We don't need asserting the compactSize uint is parseable since it\n // was already checked during `validateVin` validation.\n // See `BitcoinTx.inputVector` docs for more details.\n (, uint256 inputsCount) = walletOutboundTxInputVector.parseVarInt();\n require(\n inputsCount == 1,\n \"Outbound transaction must have a single input\"\n );\n\n bytes memory input = walletOutboundTxInputVector.extractInputAtIndex(0);\n\n outpointTxHash = input.extractInputTxIdLE();\n\n outpointIndex = BTCUtils.reverseUint32(\n uint32(input.extractTxIndexLE())\n );\n\n // There is only one input in the transaction. Input has an outpoint\n // field that is a reference to the transaction being spent (see\n // `BitcoinTx` docs). The outpoint contains the hash of the transaction\n // to spend (`outpointTxHash`) and the index of the specific output\n // from that transaction (`outpointIndex`).\n return (outpointTxHash, outpointIndex);\n }\n}\n\n/// @title Bridge redemption\n/// @notice The library handles the logic for redeeming Bitcoin balances from\n/// the Bridge.\n/// @dev To initiate a redemption, a user with a Bank balance supplies\n/// a Bitcoin address. Then, the system calculates the redemption fee, and\n/// releases balance to the provided Bitcoin address. Just like in case of\n/// sweeps of revealed deposits, redemption requests are processed in\n/// batches and require SPV proof to be submitted to the Bridge.\nlibrary Redemption {\n using BridgeState for BridgeState.Storage;\n using Wallets for BridgeState.Storage;\n using BitcoinTx for BridgeState.Storage;\n\n using BTCUtils for bytes;\n using BytesLib for bytes;\n\n /// @notice Represents a redemption request.\n struct RedemptionRequest {\n // ETH address of the redeemer who created the request.\n address redeemer;\n // Requested TBTC amount in satoshi.\n uint64 requestedAmount;\n // Treasury TBTC fee in satoshi at the moment of request creation.\n uint64 treasuryFee;\n // Transaction maximum BTC fee in satoshi at the moment of request\n // creation.\n uint64 txMaxFee;\n // UNIX timestamp the request was created at.\n // XXX: Unsigned 32-bit int unix seconds, will break February 7th 2106.\n uint32 requestedAt;\n // This struct doesn't contain `__gap` property as the structure is stored\n // in a mapping, mappings store values in different slots and they are\n // not contiguous with other values.\n }\n\n /// @notice Represents an outcome of the redemption Bitcoin transaction\n /// outputs processing.\n struct RedemptionTxOutputsInfo {\n // Sum of all outputs values i.e. all redemptions and change value,\n // if present.\n uint256 outputsTotalValue;\n // Total TBTC value in satoshi that should be burned by the Bridge.\n // It includes the total amount of all BTC redeemed in the transaction\n // and the fee paid to BTC miners for the redemption transaction.\n uint64 totalBurnableValue;\n // Total TBTC value in satoshi that should be transferred to\n // the treasury. It is a sum of all treasury fees paid by all\n // redeemers included in the redemption transaction.\n uint64 totalTreasuryFee;\n // Index of the change output. The change output becomes\n // the new main wallet's UTXO.\n uint32 changeIndex;\n // Value in satoshi of the change output.\n uint64 changeValue;\n // This struct doesn't contain `__gap` property as the structure is not\n // stored, it is used as a function's memory argument.\n }\n\n /// @notice Represents temporary information needed during the processing of\n /// the redemption Bitcoin transaction outputs. This structure is an\n /// internal one and should not be exported outside of the redemption\n /// transaction processing code.\n /// @dev Allows to mitigate \"stack too deep\" errors on EVM.\n struct RedemptionTxOutputsProcessingInfo {\n // The first output starting index in the transaction.\n uint256 outputStartingIndex;\n // The number of outputs in the transaction.\n uint256 outputsCount;\n // P2PKH script for the wallet. Needed to determine the change output.\n bytes32 walletP2PKHScriptKeccak;\n // P2WPKH script for the wallet. Needed to determine the change output.\n bytes32 walletP2WPKHScriptKeccak;\n // This struct doesn't contain `__gap` property as the structure is not\n // stored, it is used as a function's memory argument.\n }\n\n event RedemptionRequested(\n bytes20 indexed walletPubKeyHash,\n bytes redeemerOutputScript,\n address indexed redeemer,\n uint64 requestedAmount,\n uint64 treasuryFee,\n uint64 txMaxFee\n );\n\n event RedemptionsCompleted(\n bytes20 indexed walletPubKeyHash,\n bytes32 redemptionTxHash\n );\n\n event RedemptionTimedOut(\n bytes20 indexed walletPubKeyHash,\n bytes redeemerOutputScript\n );\n\n /// @notice Requests redemption of the given amount from the specified\n /// wallet to the redeemer Bitcoin output script.\n /// This function handles the simplest case, where balance owner is\n /// the redeemer.\n /// @param walletPubKeyHash The 20-byte wallet public key hash (computed\n /// using Bitcoin HASH160 over the compressed ECDSA public key).\n /// @param mainUtxo Data of the wallet's main UTXO, as currently known on\n /// the Ethereum chain.\n /// @param balanceOwner The address of the Bank balance owner whose balance\n /// is getting redeemed. Balance owner address is stored as\n /// a redeemer address who will be able co claim back the Bank\n /// balance if anything goes wrong during the redemption.\n /// @param redeemerOutputScript The redeemer's length-prefixed output\n /// script (P2PKH, P2WPKH, P2SH or P2WSH) that will be used to lock\n /// redeemed BTC.\n /// @param amount Requested amount in satoshi. This is also the Bank balance\n /// that is taken from the `balanceOwner` upon request.\n /// Once the request is handled, the actual amount of BTC locked\n /// on the redeemer output script will be always lower than this value\n /// since the treasury and Bitcoin transaction fees must be incurred.\n /// The minimal amount satisfying the request can be computed as:\n /// `amount - (amount / redemptionTreasuryFeeDivisor) - redemptionTxMaxFee`.\n /// Fees values are taken at the moment of request creation.\n /// @dev Requirements:\n /// - Wallet behind `walletPubKeyHash` must be live,\n /// - `mainUtxo` components must point to the recent main UTXO\n /// of the given wallet, as currently known on the Ethereum chain,\n /// - `redeemerOutputScript` must be a proper Bitcoin script,\n /// - `redeemerOutputScript` cannot have wallet PKH as payload,\n /// - `amount` must be above or equal the `redemptionDustThreshold`,\n /// - Given `walletPubKeyHash` and `redeemerOutputScript` pair can be\n /// used for only one pending request at the same time,\n /// - Wallet must have enough Bitcoin balance to proceed the request,\n /// - Balance owner must make an allowance in the Bank that the Bridge\n /// contract can spend the given `amount`.\n function requestRedemption(\n BridgeState.Storage storage self,\n bytes20 walletPubKeyHash,\n BitcoinTx.UTXO calldata mainUtxo,\n address balanceOwner,\n bytes calldata redeemerOutputScript,\n uint64 amount\n ) external {\n requestRedemption(\n self,\n walletPubKeyHash,\n mainUtxo,\n balanceOwner,\n balanceOwner,\n redeemerOutputScript,\n amount\n );\n }\n\n /// @notice Requests redemption of the given amount from the specified\n /// wallet to the redeemer Bitcoin output script. Used by\n /// `Bridge.receiveBalanceApproval`. Can handle more complex cases\n /// where balance owner may be someone else than the redeemer.\n /// @param balanceOwner The address of the Bank balance owner whose balance\n /// is getting redeemed.\n /// @param amount Requested amount in satoshi. This is also the Bank balance\n /// that is taken from the `balanceOwner` upon request.\n /// Once the request is handled, the actual amount of BTC locked\n /// on the redeemer output script will be always lower than this value\n /// since the treasury and Bitcoin transaction fees must be incurred.\n /// The minimal amount satisfying the request can be computed as:\n /// `amount - (amount / redemptionTreasuryFeeDivisor) - redemptionTxMaxFee`.\n /// Fees values are taken at the moment of request creation.\n /// @param redemptionData ABI-encoded redemption data:\n /// [\n /// address redeemer,\n /// bytes20 walletPubKeyHash,\n /// bytes32 mainUtxoTxHash,\n /// uint32 mainUtxoTxOutputIndex,\n /// uint64 mainUtxoTxOutputValue,\n /// bytes redeemerOutputScript\n /// ]\n ///\n /// - redeemer: The Ethereum address of the redeemer who will be able\n /// to claim Bank balance if anything goes wrong during the redemption.\n /// In the most basic case, when someone redeems their Bitcoin\n /// balance from the Bank, `balanceOwner` is the same as `redeemer`.\n /// However, when a Vault is redeeming part of its balance for some\n /// redeemer address (for example, someone who has earlier deposited\n /// into that Vault), `balanceOwner` is the Vault, and `redeemer` is\n /// the address for which the vault is redeeming its balance to,\n /// - walletPubKeyHash: The 20-byte wallet public key hash (computed\n /// using Bitcoin HASH160 over the compressed ECDSA public key),\n /// - mainUtxoTxHash: Data of the wallet's main UTXO TX hash, as\n /// currently known on the Ethereum chain,\n /// - mainUtxoTxOutputIndex: Data of the wallet's main UTXO output\n /// index, as currently known on Ethereum chain,\n /// - mainUtxoTxOutputValue: Data of the wallet's main UTXO output\n /// value, as currently known on Ethereum chain,\n /// - redeemerOutputScript The redeemer's length-prefixed output\n /// script (P2PKH, P2WPKH, P2SH or P2WSH) that will be used to lock\n /// redeemed BTC.\n /// @dev Requirements:\n /// - Wallet behind `walletPubKeyHash` must be live,\n /// - `mainUtxo*` components must point to the recent main UTXO\n /// of the given wallet, as currently known on the Ethereum chain,\n /// - `redeemerOutputScript` must be a proper Bitcoin script,\n /// - `redeemerOutputScript` cannot have wallet PKH as payload,\n /// - `amount` must be above or equal the `redemptionDustThreshold`,\n /// - Given `walletPubKeyHash` and `redeemerOutputScript` pair can be\n /// used for only one pending request at the same time,\n /// - Wallet must have enough Bitcoin balance to proceed the request,\n /// - Balance owner must make an allowance in the Bank that the Bridge\n /// contract can spend the given `amount`.\n function requestRedemption(\n BridgeState.Storage storage self,\n address balanceOwner,\n uint64 amount,\n bytes calldata redemptionData\n ) external {\n (\n address redeemer,\n bytes20 walletPubKeyHash,\n bytes32 mainUtxoTxHash,\n uint32 mainUtxoTxOutputIndex,\n uint64 mainUtxoTxOutputValue,\n bytes memory redeemerOutputScript\n ) = abi.decode(\n redemptionData,\n (address, bytes20, bytes32, uint32, uint64, bytes)\n );\n\n requestRedemption(\n self,\n walletPubKeyHash,\n BitcoinTx.UTXO(\n mainUtxoTxHash,\n mainUtxoTxOutputIndex,\n mainUtxoTxOutputValue\n ),\n balanceOwner,\n redeemer,\n redeemerOutputScript,\n amount\n );\n }\n\n /// @notice Requests redemption of the given amount from the specified\n /// wallet to the redeemer Bitcoin output script.\n /// @param walletPubKeyHash The 20-byte wallet public key hash (computed\n /// using Bitcoin HASH160 over the compressed ECDSA public key).\n /// @param mainUtxo Data of the wallet's main UTXO, as currently known on\n /// the Ethereum chain.\n /// @param balanceOwner The address of the Bank balance owner whose balance\n /// is getting redeemed.\n /// @param redeemer The Ethereum address of the redeemer who will be able to\n /// claim Bank balance if anything goes wrong during the redemption.\n /// In the most basic case, when someone redeems their Bitcoin\n /// balance from the Bank, `balanceOwner` is the same as `redeemer`.\n /// However, when a Vault is redeeming part of its balance for some\n /// redeemer address (for example, someone who has earlier deposited\n /// into that Vault), `balanceOwner` is the Vault, and `redeemer` is\n /// the address for which the vault is redeeming its balance to.\n /// @param redeemerOutputScript The redeemer's length-prefixed output\n /// script (P2PKH, P2WPKH, P2SH or P2WSH) that will be used to lock\n /// redeemed BTC.\n /// @param amount Requested amount in satoshi. This is also the Bank balance\n /// that is taken from the `balanceOwner` upon request.\n /// Once the request is handled, the actual amount of BTC locked\n /// on the redeemer output script will be always lower than this value\n /// since the treasury and Bitcoin transaction fees must be incurred.\n /// The minimal amount satisfying the request can be computed as:\n /// `amount - (amount / redemptionTreasuryFeeDivisor) - redemptionTxMaxFee`.\n /// Fees values are taken at the moment of request creation.\n /// @dev Requirements:\n /// - Wallet behind `walletPubKeyHash` must be live,\n /// - `mainUtxo` components must point to the recent main UTXO\n /// of the given wallet, as currently known on the Ethereum chain,\n /// - `redeemerOutputScript` must be a proper Bitcoin script,\n /// - `redeemerOutputScript` cannot have wallet PKH as payload,\n /// - `amount` must be above or equal the `redemptionDustThreshold`,\n /// - Given `walletPubKeyHash` and `redeemerOutputScript` pair can be\n /// used for only one pending request at the same time,\n /// - Wallet must have enough Bitcoin balance to proceed the request,\n /// - Balance owner must make an allowance in the Bank that the Bridge\n /// contract can spend the given `amount`.\n function requestRedemption(\n BridgeState.Storage storage self,\n bytes20 walletPubKeyHash,\n BitcoinTx.UTXO memory mainUtxo,\n address balanceOwner,\n address redeemer,\n bytes memory redeemerOutputScript,\n uint64 amount\n ) internal {\n Wallets.Wallet storage wallet = self.registeredWallets[\n walletPubKeyHash\n ];\n\n require(\n wallet.state == Wallets.WalletState.Live,\n \"Wallet must be in Live state\"\n );\n\n bytes32 mainUtxoHash = wallet.mainUtxoHash;\n require(\n mainUtxoHash != bytes32(0),\n \"No main UTXO for the given wallet\"\n );\n require(\n keccak256(\n abi.encodePacked(\n mainUtxo.txHash,\n mainUtxo.txOutputIndex,\n mainUtxo.txOutputValue\n )\n ) == mainUtxoHash,\n \"Invalid main UTXO data\"\n );\n\n // Validate if redeemer output script is a correct standard type\n // (P2PKH, P2WPKH, P2SH or P2WSH). This is done by using\n // `BTCUtils.extractHashAt` on it. Such a function extracts the payload\n // properly only from standard outputs so if it succeeds, we have a\n // guarantee the redeemer output script is proper. The underlying way\n // of validation is the same as in tBTC v1.\n bytes memory redeemerOutputScriptPayload = redeemerOutputScript\n .extractHashAt(0, redeemerOutputScript.length);\n\n require(\n redeemerOutputScriptPayload.length > 0,\n \"Redeemer output script must be a standard type\"\n );\n // Check if the redeemer output script payload does not point to the\n // wallet public key hash.\n require(\n redeemerOutputScriptPayload.length != 20 ||\n walletPubKeyHash != redeemerOutputScriptPayload.slice20(0),\n \"Redeemer output script must not point to the wallet PKH\"\n );\n\n require(\n amount >= self.redemptionDustThreshold,\n \"Redemption amount too small\"\n );\n\n // The redemption key is built on top of the wallet public key hash\n // and redeemer output script pair. That means there can be only one\n // request asking for redemption from the given wallet to the given\n // BTC script at the same time.\n uint256 redemptionKey = getRedemptionKey(\n walletPubKeyHash,\n redeemerOutputScript\n );\n\n // Check if given redemption key is not used by a pending redemption.\n // There is no need to check for existence in `timedOutRedemptions`\n // since the wallet's state is changed to other than Live after\n // first time out is reported so making new requests is not possible.\n // slither-disable-next-line incorrect-equality\n require(\n self.pendingRedemptions[redemptionKey].requestedAt == 0,\n \"There is a pending redemption request from this wallet to the same address\"\n );\n\n // No need to check whether `amount - treasuryFee - txMaxFee > 0`\n // since the `redemptionDustThreshold` should force that condition\n // to be always true.\n uint64 treasuryFee = self.redemptionTreasuryFeeDivisor > 0\n ? amount / self.redemptionTreasuryFeeDivisor\n : 0;\n uint64 txMaxFee = self.redemptionTxMaxFee;\n\n // The main wallet UTXO's value doesn't include all pending redemptions.\n // To determine if the requested redemption can be performed by the\n // wallet we need to subtract the total value of all pending redemptions\n // from that wallet's main UTXO value. Given that the treasury fee is\n // not redeemed from the wallet, we are subtracting it.\n wallet.pendingRedemptionsValue += amount - treasuryFee;\n require(\n mainUtxo.txOutputValue >= wallet.pendingRedemptionsValue,\n \"Insufficient wallet funds\"\n );\n\n self.pendingRedemptions[redemptionKey] = RedemptionRequest(\n redeemer,\n amount,\n treasuryFee,\n txMaxFee,\n /* solhint-disable-next-line not-rely-on-time */\n uint32(block.timestamp)\n );\n\n // slither-disable-next-line reentrancy-events\n emit RedemptionRequested(\n walletPubKeyHash,\n redeemerOutputScript,\n redeemer,\n amount,\n treasuryFee,\n txMaxFee\n );\n\n self.bank.transferBalanceFrom(balanceOwner, address(this), amount);\n }\n\n /// @notice Used by the wallet to prove the BTC redemption transaction\n /// and to make the necessary bookkeeping. Redemption is only\n /// accepted if it satisfies SPV proof.\n ///\n /// The function is performing Bank balance updates by burning\n /// the total redeemed Bitcoin amount from Bridge balance and\n /// transferring the treasury fee sum to the treasury address.\n ///\n /// It is possible to prove the given redemption only one time.\n /// @param redemptionTx Bitcoin redemption transaction data.\n /// @param redemptionProof Bitcoin redemption proof data.\n /// @param mainUtxo Data of the wallet's main UTXO, as currently known on\n /// the Ethereum chain.\n /// @param walletPubKeyHash 20-byte public key hash (computed using Bitcoin\n /// HASH160 over the compressed ECDSA public key) of the wallet which\n /// performed the redemption transaction.\n /// @dev Requirements:\n /// - `redemptionTx` components must match the expected structure. See\n /// `BitcoinTx.Info` docs for reference. Their values must exactly\n /// correspond to appropriate Bitcoin transaction fields to produce\n /// a provable transaction hash,\n /// - The `redemptionTx` should represent a Bitcoin transaction with\n /// exactly 1 input that refers to the wallet's main UTXO. That\n /// transaction should have 1..n outputs handling existing pending\n /// redemption requests or pointing to reported timed out requests.\n /// There can be also 1 optional output representing the\n /// change and pointing back to the 20-byte wallet public key hash.\n /// The change should be always present if the redeemed value sum\n /// is lower than the total wallet's BTC balance,\n /// - `redemptionProof` components must match the expected structure.\n /// See `BitcoinTx.Proof` docs for reference. The `bitcoinHeaders`\n /// field must contain a valid number of block headers, not less\n /// than the `txProofDifficultyFactor` contract constant,\n /// - `mainUtxo` components must point to the recent main UTXO\n /// of the given wallet, as currently known on the Ethereum chain.\n /// Additionally, the recent main UTXO on Ethereum must be set,\n /// - `walletPubKeyHash` must be connected with the main UTXO used\n /// as transaction single input.\n /// Other remarks:\n /// - Putting the change output as the first transaction output can\n /// save some gas because the output processing loop begins each\n /// iteration by checking whether the given output is the change\n /// thus uses some gas for making the comparison. Once the change\n /// is identified, that check is omitted in further iterations.\n function submitRedemptionProof(\n BridgeState.Storage storage self,\n BitcoinTx.Info calldata redemptionTx,\n BitcoinTx.Proof calldata redemptionProof,\n BitcoinTx.UTXO calldata mainUtxo,\n bytes20 walletPubKeyHash\n ) external {\n // Wallet state validation is performed in the `resolveRedeemingWallet`\n // function.\n\n // The actual transaction proof is performed here. After that point, we\n // can assume the transaction happened on Bitcoin chain and has\n // a sufficient number of confirmations as determined by\n // `txProofDifficultyFactor` constant.\n bytes32 redemptionTxHash = self.validateProof(\n redemptionTx,\n redemptionProof\n );\n\n Wallets.Wallet storage wallet = resolveRedeemingWallet(\n self,\n walletPubKeyHash,\n mainUtxo\n );\n\n // Process the redemption transaction input. Specifically, check if it\n // refers to the expected wallet's main UTXO.\n OutboundTx.processWalletOutboundTxInput(\n self,\n redemptionTx.inputVector,\n mainUtxo\n );\n\n // Process redemption transaction outputs to extract some info required\n // for further processing.\n RedemptionTxOutputsInfo memory outputsInfo = processRedemptionTxOutputs(\n self,\n redemptionTx.outputVector,\n walletPubKeyHash\n );\n\n require(\n mainUtxo.txOutputValue - outputsInfo.outputsTotalValue <=\n self.redemptionTxMaxTotalFee,\n \"Transaction fee is too high\"\n );\n\n if (outputsInfo.changeValue > 0) {\n // If the change value is grater than zero, it means the change\n // output exists and can be used as new wallet's main UTXO.\n wallet.mainUtxoHash = keccak256(\n abi.encodePacked(\n redemptionTxHash,\n outputsInfo.changeIndex,\n outputsInfo.changeValue\n )\n );\n } else {\n // If the change value is zero, it means the change output doesn't\n // exists and no funds left on the wallet. Delete the main UTXO\n // for that wallet to represent that state in a proper way.\n delete wallet.mainUtxoHash;\n }\n\n wallet.pendingRedemptionsValue -= outputsInfo.totalBurnableValue;\n\n emit RedemptionsCompleted(walletPubKeyHash, redemptionTxHash);\n\n self.bank.decreaseBalance(outputsInfo.totalBurnableValue);\n\n if (outputsInfo.totalTreasuryFee > 0) {\n self.bank.transferBalance(\n self.treasury,\n outputsInfo.totalTreasuryFee\n );\n }\n }\n\n /// @notice Resolves redeeming wallet based on the provided wallet public\n /// key hash. Validates the wallet state and current main UTXO, as\n /// currently known on the Ethereum chain.\n /// @param walletPubKeyHash public key hash of the wallet proving the sweep\n /// Bitcoin transaction.\n /// @param mainUtxo Data of the wallet's main UTXO, as currently known on\n /// the Ethereum chain.\n /// @return wallet Data of the sweeping wallet.\n /// @dev Requirements:\n /// - Sweeping wallet must be either in Live or MovingFunds state,\n /// - Main UTXO of the redeeming wallet must exists in the storage,\n /// - The passed `mainUTXO` parameter must be equal to the stored one.\n function resolveRedeemingWallet(\n BridgeState.Storage storage self,\n bytes20 walletPubKeyHash,\n BitcoinTx.UTXO calldata mainUtxo\n ) internal view returns (Wallets.Wallet storage wallet) {\n wallet = self.registeredWallets[walletPubKeyHash];\n\n // Assert that main UTXO for passed wallet exists in storage.\n bytes32 mainUtxoHash = wallet.mainUtxoHash;\n require(mainUtxoHash != bytes32(0), \"No main UTXO for given wallet\");\n\n // Assert that passed main UTXO parameter is the same as in storage and\n // can be used for further processing.\n require(\n keccak256(\n abi.encodePacked(\n mainUtxo.txHash,\n mainUtxo.txOutputIndex,\n mainUtxo.txOutputValue\n )\n ) == mainUtxoHash,\n \"Invalid main UTXO data\"\n );\n\n Wallets.WalletState walletState = wallet.state;\n require(\n walletState == Wallets.WalletState.Live ||\n walletState == Wallets.WalletState.MovingFunds,\n \"Wallet must be in Live or MovingFunds state\"\n );\n }\n\n /// @notice Processes the Bitcoin redemption transaction output vector.\n /// It extracts each output and tries to identify it as a pending\n /// redemption request, reported timed out request, or change.\n /// Reverts if one of the outputs cannot be recognized properly.\n /// This function also marks each request as processed by removing\n /// them from `pendingRedemptions` mapping.\n /// @param redemptionTxOutputVector Bitcoin redemption transaction output\n /// vector. This function assumes vector's structure is valid so it\n /// must be validated using e.g. `BTCUtils.validateVout` function\n /// before it is passed here.\n /// @param walletPubKeyHash 20-byte public key hash (computed using Bitcoin\n /// HASH160 over the compressed ECDSA public key) of the wallet which\n /// performed the redemption transaction.\n /// @return info Outcomes of the processing.\n function processRedemptionTxOutputs(\n BridgeState.Storage storage self,\n bytes memory redemptionTxOutputVector,\n bytes20 walletPubKeyHash\n ) internal returns (RedemptionTxOutputsInfo memory info) {\n // Determining the total number of redemption transaction outputs in\n // the same way as for number of inputs. See `BitcoinTx.outputVector`\n // docs for more details.\n (\n uint256 outputsCompactSizeUintLength,\n uint256 outputsCount\n ) = redemptionTxOutputVector.parseVarInt();\n\n // To determine the first output starting index, we must jump over\n // the compactSize uint which prepends the output vector. One byte\n // must be added because `BtcUtils.parseVarInt` does not include\n // compactSize uint tag in the returned length.\n //\n // For >= 0 && <= 252, `BTCUtils.determineVarIntDataLengthAt`\n // returns `0`, so we jump over one byte of compactSize uint.\n //\n // For >= 253 && <= 0xffff there is `0xfd` tag,\n // `BTCUtils.determineVarIntDataLengthAt` returns `2` (no\n // tag byte included) so we need to jump over 1+2 bytes of\n // compactSize uint.\n //\n // Please refer `BTCUtils` library and compactSize uint\n // docs in `BitcoinTx` library for more details.\n uint256 outputStartingIndex = 1 + outputsCompactSizeUintLength;\n\n // Calculate the keccak256 for two possible wallet's P2PKH or P2WPKH\n // scripts that can be used to lock the change. This is done upfront to\n // save on gas. Both scripts have a strict format defined by Bitcoin.\n //\n // The P2PKH script has the byte format: <0x1976a914> <20-byte PKH> <0x88ac>.\n // According to https://en.bitcoin.it/wiki/Script#Opcodes this translates to:\n // - 0x19: Byte length of the entire script\n // - 0x76: OP_DUP\n // - 0xa9: OP_HASH160\n // - 0x14: Byte length of the public key hash\n // - 0x88: OP_EQUALVERIFY\n // - 0xac: OP_CHECKSIG\n // which matches the P2PKH structure as per:\n // https://en.bitcoin.it/wiki/Transaction#Pay-to-PubkeyHash\n bytes32 walletP2PKHScriptKeccak = keccak256(\n abi.encodePacked(BitcoinTx.makeP2PKHScript(walletPubKeyHash))\n );\n // The P2WPKH script has the byte format: <0x160014> <20-byte PKH>.\n // According to https://en.bitcoin.it/wiki/Script#Opcodes this translates to:\n // - 0x16: Byte length of the entire script\n // - 0x00: OP_0\n // - 0x14: Byte length of the public key hash\n // which matches the P2WPKH structure as per:\n // https://github.com/bitcoin/bips/blob/master/bip-0141.mediawiki#P2WPKH\n bytes32 walletP2WPKHScriptKeccak = keccak256(\n abi.encodePacked(BitcoinTx.makeP2WPKHScript(walletPubKeyHash))\n );\n\n return\n processRedemptionTxOutputs(\n self,\n redemptionTxOutputVector,\n walletPubKeyHash,\n RedemptionTxOutputsProcessingInfo(\n outputStartingIndex,\n outputsCount,\n walletP2PKHScriptKeccak,\n walletP2WPKHScriptKeccak\n )\n );\n }\n\n /// @notice Processes all outputs from the redemption transaction. Tries to\n /// identify output as a change output, pending redemption request\n /// or reported redemption. Reverts if one of the outputs cannot be\n /// recognized properly. Marks each request as processed by removing\n /// them from `pendingRedemptions` mapping.\n /// @param redemptionTxOutputVector Bitcoin redemption transaction output\n /// vector. This function assumes vector's structure is valid so it\n /// must be validated using e.g. `BTCUtils.validateVout` function\n /// before it is passed here.\n /// @param walletPubKeyHash 20-byte public key hash (computed using Bitcoin\n /// HASH160 over the compressed ECDSA public key) of the wallet which\n /// performed the redemption transaction.\n /// @param processInfo RedemptionTxOutputsProcessingInfo identifying output\n /// starting index, the number of outputs and possible wallet change\n /// P2PKH and P2WPKH scripts.\n function processRedemptionTxOutputs(\n BridgeState.Storage storage self,\n bytes memory redemptionTxOutputVector,\n bytes20 walletPubKeyHash,\n RedemptionTxOutputsProcessingInfo memory processInfo\n ) internal returns (RedemptionTxOutputsInfo memory resultInfo) {\n // Helper flag indicating whether there was at least one redemption\n // output present (redemption must be either pending or reported as\n // timed out).\n bool redemptionPresent = false;\n\n // Outputs processing loop.\n for (uint256 i = 0; i < processInfo.outputsCount; i++) {\n uint256 outputLength = redemptionTxOutputVector\n .determineOutputLengthAt(processInfo.outputStartingIndex);\n\n // Extract the value from given output.\n uint64 outputValue = redemptionTxOutputVector.extractValueAt(\n processInfo.outputStartingIndex\n );\n\n // The output consists of an 8-byte value and a variable length\n // script. To hash that script we slice the output starting from\n // 9th byte until the end.\n uint256 scriptLength = outputLength - 8;\n uint256 outputScriptStart = processInfo.outputStartingIndex + 8;\n\n bytes32 outputScriptHash;\n /* solhint-disable-next-line no-inline-assembly */\n assembly {\n // The first argument to assembly keccak256 is the pointer.\n // We point to `redemptionTxOutputVector` but at the position\n // indicated by `outputScriptStart`. To load that position, we\n // need to call `add(outputScriptStart, 32)` because\n // `outputScriptStart` has 32 bytes.\n outputScriptHash := keccak256(\n add(redemptionTxOutputVector, add(outputScriptStart, 32)),\n scriptLength\n )\n }\n\n if (\n resultInfo.changeValue == 0 &&\n (outputScriptHash == processInfo.walletP2PKHScriptKeccak ||\n outputScriptHash == processInfo.walletP2WPKHScriptKeccak) &&\n outputValue > 0\n ) {\n // If we entered here, that means the change output with a\n // proper non-zero value was found.\n resultInfo.changeIndex = uint32(i);\n resultInfo.changeValue = outputValue;\n } else {\n // If we entered here, that the means the given output is\n // supposed to represent a redemption.\n (\n uint64 burnableValue,\n uint64 treasuryFee\n ) = processNonChangeRedemptionTxOutput(\n self,\n _getRedemptionKey(walletPubKeyHash, outputScriptHash),\n outputValue\n );\n resultInfo.totalBurnableValue += burnableValue;\n resultInfo.totalTreasuryFee += treasuryFee;\n redemptionPresent = true;\n }\n\n resultInfo.outputsTotalValue += outputValue;\n\n // Make the `outputStartingIndex` pointing to the next output by\n // increasing it by current output's length.\n processInfo.outputStartingIndex += outputLength;\n }\n\n // Protect against the cases when there is only a single change output\n // referring back to the wallet PKH and just burning main UTXO value\n // for transaction fees.\n require(\n redemptionPresent,\n \"Redemption transaction must process at least one redemption\"\n );\n }\n\n /// @notice Processes a single redemption transaction output. Tries to\n /// identify output as a pending redemption request or reported\n /// redemption timeout. Output script passed to this function must\n /// not be the change output. Such output needs to be identified\n /// separately before calling this function.\n /// Reverts if output is neither requested pending redemption nor\n /// requested and reported timed-out redemption.\n /// This function also marks each pending request as processed by\n /// removing them from `pendingRedemptions` mapping.\n /// @param redemptionKey Redemption key of the output being processed.\n /// @param outputValue Value of the output being processed.\n /// @return burnableValue The value burnable as a result of processing this\n /// single redemption output. This value needs to be summed up with\n /// burnable values of all other outputs to evaluate total burnable\n /// value for the entire redemption transaction. This value is 0\n /// for a timed-out redemption request.\n /// @return treasuryFee The treasury fee from this single redemption output.\n /// This value needs to be summed up with treasury fees of all other\n /// outputs to evaluate the total treasury fee for the entire\n /// redemption transaction. This value is 0 for a timed-out\n /// redemption request.\n /// @dev Requirements:\n /// - This function should be called only if the given output\n /// represents redemption. It must not be the change output.\n function processNonChangeRedemptionTxOutput(\n BridgeState.Storage storage self,\n uint256 redemptionKey,\n uint64 outputValue\n ) internal returns (uint64 burnableValue, uint64 treasuryFee) {\n if (self.pendingRedemptions[redemptionKey].requestedAt != 0) {\n // If we entered here, that means the output was identified\n // as a pending redemption request.\n RedemptionRequest storage request = self.pendingRedemptions[\n redemptionKey\n ];\n // Compute the request's redeemable amount as the requested\n // amount reduced by the treasury fee. The request's\n // minimal amount is then the redeemable amount reduced by\n // the maximum transaction fee.\n uint64 redeemableAmount = request.requestedAmount -\n request.treasuryFee;\n // Output value must fit between the request's redeemable\n // and minimal amounts to be deemed valid.\n require(\n redeemableAmount - request.txMaxFee <= outputValue &&\n outputValue <= redeemableAmount,\n \"Output value is not within the acceptable range of the pending request\"\n );\n // Add the redeemable amount to the total burnable value\n // the Bridge will use to decrease its balance in the Bank.\n burnableValue = redeemableAmount;\n // Add the request's treasury fee to the total treasury fee\n // value the Bridge will transfer to the treasury.\n treasuryFee = request.treasuryFee;\n // Request was properly handled so remove its redemption\n // key from the mapping to make it reusable for further\n // requests.\n delete self.pendingRedemptions[redemptionKey];\n } else {\n // If we entered here, the output is not a redemption\n // request but there is still a chance the given output is\n // related to a reported timed out redemption request.\n // If so, check if the output value matches the request\n // amount to confirm this is an overdue request fulfillment\n // then bypass this output and process the subsequent\n // ones. That also means the wallet was already punished\n // for the inactivity. Otherwise, just revert.\n RedemptionRequest storage request = self.timedOutRedemptions[\n redemptionKey\n ];\n\n require(\n request.requestedAt != 0,\n \"Output is a non-requested redemption\"\n );\n\n uint64 redeemableAmount = request.requestedAmount -\n request.treasuryFee;\n\n require(\n redeemableAmount - request.txMaxFee <= outputValue &&\n outputValue <= redeemableAmount,\n \"Output value is not within the acceptable range of the timed out request\"\n );\n\n delete self.timedOutRedemptions[redemptionKey];\n }\n }\n\n /// @notice Notifies that there is a pending redemption request associated\n /// with the given wallet, that has timed out. The redemption\n /// request is identified by the key built as\n /// `keccak256(keccak256(redeemerOutputScript) | walletPubKeyHash)`.\n /// The results of calling this function:\n /// - the pending redemptions value for the wallet will be decreased\n /// by the requested amount (minus treasury fee),\n /// - the tokens taken from the redeemer on redemption request will\n /// be returned to the redeemer,\n /// - the request will be moved from pending redemptions to\n /// timed-out redemptions,\n /// - if the state of the wallet is `Live` or `MovingFunds`, the\n /// wallet operators will be slashed and the notifier will be\n /// rewarded,\n /// - if the state of wallet is `Live`, the wallet will be closed or\n /// marked as `MovingFunds` (depending on the presence or absence\n /// of the wallet's main UTXO) and the wallet will no longer be\n /// marked as the active wallet (if it was marked as such).\n /// @param walletPubKeyHash 20-byte public key hash of the wallet.\n /// @param walletMembersIDs Identifiers of the wallet signing group members.\n /// @param redeemerOutputScript The redeemer's length-prefixed output\n /// script (P2PKH, P2WPKH, P2SH or P2WSH).\n /// @dev Requirements:\n /// - The wallet must be in the Live or MovingFunds or Terminated state,\n /// - The redemption request identified by `walletPubKeyHash` and\n /// `redeemerOutputScript` must exist,\n /// - The expression `keccak256(abi.encode(walletMembersIDs))` must\n /// be exactly the same as the hash stored under `membersIdsHash`\n /// for the given `walletID`. Those IDs are not directly stored\n /// in the contract for gas efficiency purposes but they can be\n /// read from appropriate `DkgResultSubmitted` and `DkgResultApproved`\n /// events of the `WalletRegistry` contract,\n /// - The amount of time defined by `redemptionTimeout` must have\n /// passed since the redemption was requested (the request must be\n /// timed-out).\n function notifyRedemptionTimeout(\n BridgeState.Storage storage self,\n bytes20 walletPubKeyHash,\n uint32[] calldata walletMembersIDs,\n bytes calldata redeemerOutputScript\n ) external {\n // Wallet state is validated in `notifyWalletRedemptionTimeout`.\n uint256 redemptionKey = getRedemptionKey(\n walletPubKeyHash,\n redeemerOutputScript\n );\n Redemption.RedemptionRequest memory request = self.pendingRedemptions[\n redemptionKey\n ];\n\n require(request.requestedAt > 0, \"Redemption request does not exist\");\n require(\n /* solhint-disable-next-line not-rely-on-time */\n request.requestedAt + self.redemptionTimeout < block.timestamp,\n \"Redemption request has not timed out\"\n );\n\n // Update the wallet's pending redemptions value\n Wallets.Wallet storage wallet = self.registeredWallets[\n walletPubKeyHash\n ];\n wallet.pendingRedemptionsValue -=\n request.requestedAmount -\n request.treasuryFee;\n\n // It is worth noting that there is no need to check if\n // `timedOutRedemption` mapping already contains the given redemption\n // key. There is no possibility to re-use a key of a reported timed-out\n // redemption because the wallet responsible for causing the timeout is\n // moved to a state that prevents it to receive new redemption requests.\n\n // Propagate timeout consequences to the wallet\n self.notifyWalletRedemptionTimeout(walletPubKeyHash, walletMembersIDs);\n\n // Move the redemption from pending redemptions to timed-out redemptions\n self.timedOutRedemptions[redemptionKey] = request;\n delete self.pendingRedemptions[redemptionKey];\n\n // slither-disable-next-line reentrancy-events\n emit RedemptionTimedOut(walletPubKeyHash, redeemerOutputScript);\n\n // Return the requested amount of tokens to the redeemer\n self.bank.transferBalance(request.redeemer, request.requestedAmount);\n }\n\n /// @notice Calculate redemption key without allocations.\n /// @param walletPubKeyHash the pubkey hash of the wallet.\n /// @param script the output script of the redemption.\n /// @return The key = keccak256(keccak256(script) | walletPubKeyHash).\n function getRedemptionKey(bytes20 walletPubKeyHash, bytes memory script)\n internal\n pure\n returns (uint256)\n {\n bytes32 scriptHash = keccak256(script);\n uint256 key;\n /* solhint-disable-next-line no-inline-assembly */\n assembly {\n mstore(0, scriptHash)\n mstore(32, walletPubKeyHash)\n key := keccak256(0, 52)\n }\n return key;\n }\n\n /// @notice Finish calculating redemption key without allocations.\n /// @param walletPubKeyHash the pubkey hash of the wallet.\n /// @param scriptHash the output script hash of the redemption.\n /// @return The key = keccak256(scriptHash | walletPubKeyHash).\n function _getRedemptionKey(bytes20 walletPubKeyHash, bytes32 scriptHash)\n internal\n pure\n returns (uint256)\n {\n uint256 key;\n /* solhint-disable-next-line no-inline-assembly */\n assembly {\n mstore(0, scriptHash)\n mstore(32, walletPubKeyHash)\n key := keccak256(0, 52)\n }\n return key;\n }\n}\n" + }, + "contracts/bridge/VendingMachine.sol": { + "content": "// SPDX-License-Identifier: GPL-3.0-only\n\npragma solidity 0.8.17;\n\nimport \"@openzeppelin/contracts/access/Ownable.sol\";\nimport \"@openzeppelin/contracts/token/ERC20/IERC20.sol\";\nimport \"@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol\";\nimport \"@thesis/solidity-contracts/contracts/token/IReceiveApproval.sol\";\n\nimport \"../token/TBTC.sol\";\nimport \"../GovernanceUtils.sol\";\n\n/// @title TBTC v2 Vending Machine\n/// @notice The Vending Machine is the owner of TBTC v2 token and can mint\n/// TBTC v2 tokens in 1:1 ratio from TBTC v1 tokens with TBTC v1\n/// deposited in the contract as collateral. TBTC v2 can be\n/// unminted back to TBTC v1 with or without a fee - fee parameter is\n/// controlled by the Governance. This implementation acts as a bridge\n/// between TBTC v1 and TBTC v2 token, allowing to mint TBTC v2 before\n/// the system is ready and fully operational without sacrificing any\n/// security guarantees and decentralization of the project.\n/// Vending Machine can be upgraded in a two-step, governance-controlled\n/// process. The new version of the Vending Machine will receive the\n/// ownership of TBTC v2 token and entire TBTC v1 balance stored as\n/// collateral. It is expected that this process will be executed before\n/// the v2 system launch. There is an optional unmint fee with a value\n/// that can be updated in a two-step, governance-controlled process.\n/// All governable parameters are controlled by two roles: update\n/// initiator and finalizer. There is a separate initiator role for\n/// unmint fee update and vending machine upgrade. The initiator\n/// proposes the change by initiating the update and the finalizer\n/// (contract owner) may approve it by finalizing the change after the\n/// governance delay passes.\ncontract VendingMachine is Ownable, IReceiveApproval {\n using SafeERC20 for IERC20;\n using SafeERC20 for TBTC;\n\n /// @notice The time delay that needs to pass between initializing and\n /// finalizing update of any governable parameter in this contract.\n uint256 public constant GOVERNANCE_DELAY = 7 days;\n\n /// @notice Divisor for precision purposes. Used to represent fractions\n /// in parameter values.\n uint256 public constant FLOATING_POINT_DIVISOR = 1e18;\n\n IERC20 public immutable tbtcV1;\n TBTC public immutable tbtcV2;\n\n /// @notice The fee for unminting TBTC v2 back into TBTC v1 represented as\n /// 1e18 precision fraction. The fee is proportional to the amount\n /// being unminted and added on the top of the amount being unminted.\n /// To calculate the fee value, the amount being unminted needs\n /// to be multiplied by `unmintFee` and divided by 1e18.\n /// For example, `unmintFee` set to 1000000000000000\n /// means that 0.001 of the amount being unminted needs to be paid\n /// to the `VendingMachine` as an unminting fee on the top of the\n /// amount being unminted.\n uint256 public unmintFee;\n uint256 public newUnmintFee;\n uint256 public unmintFeeUpdateInitiatedTimestamp;\n address public unmintFeeUpdateInitiator;\n\n /// @notice The address of a new vending machine. Set only when the upgrade\n /// process is pending. Once the upgrade gets finalized, the new\n /// vending machine will become an owner of TBTC v2 token.\n address public newVendingMachine;\n uint256 public vendingMachineUpgradeInitiatedTimestamp;\n address public vendingMachineUpgradeInitiator;\n\n event UnmintFeeUpdateInitiated(uint256 newUnmintFee, uint256 timestamp);\n event UnmintFeeUpdated(uint256 newUnmintFee);\n\n event VendingMachineUpgradeInitiated(\n address newVendingMachine,\n uint256 timestamp\n );\n event VendingMachineUpgraded(address newVendingMachine);\n\n event Minted(address indexed recipient, uint256 amount);\n event Unminted(address indexed recipient, uint256 amount, uint256 fee);\n\n modifier only(address authorizedCaller) {\n require(msg.sender == authorizedCaller, \"Caller is not authorized\");\n _;\n }\n\n modifier onlyAfterGovernanceDelay(uint256 changeInitiatedTimestamp) {\n GovernanceUtils.onlyAfterGovernanceDelay(\n changeInitiatedTimestamp,\n GOVERNANCE_DELAY\n );\n _;\n }\n\n constructor(\n IERC20 _tbtcV1,\n TBTC _tbtcV2,\n uint256 _unmintFee\n ) {\n tbtcV1 = _tbtcV1;\n tbtcV2 = _tbtcV2;\n unmintFee = _unmintFee;\n\n unmintFeeUpdateInitiator = msg.sender;\n vendingMachineUpgradeInitiator = msg.sender;\n }\n\n /// @notice Mints TBTC v2 to the caller from TBTC v1 with 1:1 ratio.\n /// The caller needs to have at least `amount` of TBTC v1 balance\n /// approved for transfer to the `VendingMachine` before calling\n /// this function.\n /// @param amount The amount of TBTC v2 to mint from TBTC v1\n function mint(uint256 amount) external {\n _mint(msg.sender, amount);\n }\n\n /// @notice Mints TBTC v2 to `from` address from TBTC v1 with 1:1 ratio.\n /// `from` address needs to have at least `amount` of TBTC v1\n /// balance approved for transfer to the `VendingMachine` before\n /// calling this function.\n /// @dev This function is a shortcut for approve + mint. Only TBTC v1\n /// caller is allowed and only TBTC v1 is allowed as a token to\n /// transfer.\n /// @param from TBTC v1 token holder minting TBTC v2 tokens\n /// @param amount The amount of TBTC v2 to mint from TBTC v1\n /// @param token TBTC v1 token address\n function receiveApproval(\n address from,\n uint256 amount,\n address token,\n bytes calldata\n ) external override {\n require(token == address(tbtcV1), \"Token is not TBTC v1\");\n require(msg.sender == address(tbtcV1), \"Only TBTC v1 caller allowed\");\n _mint(from, amount);\n }\n\n /// @notice Unmints TBTC v2 from the caller into TBTC v1. Depending on\n /// `unmintFee` value, may require paying an additional unmint fee\n /// in TBTC v2 in addition to the amount being unminted. To see\n /// what is the value of the fee, please call `unmintFeeFor(amount)`\n /// function. The caller needs to have at least\n /// `amount + unmintFeeFor(amount)` of TBTC v2 balance approved for\n /// transfer to the `VendingMachine` before calling this function.\n /// @param amount The amount of TBTC v2 to unmint to TBTC v1\n function unmint(uint256 amount) external {\n uint256 fee = unmintFeeFor(amount);\n emit Unminted(msg.sender, amount, fee);\n\n require(\n tbtcV2.balanceOf(msg.sender) >= amount + fee,\n \"Amount + fee exceeds TBTC v2 balance\"\n );\n\n tbtcV2.safeTransferFrom(msg.sender, address(this), fee);\n tbtcV2.burnFrom(msg.sender, amount);\n tbtcV1.safeTransfer(msg.sender, amount);\n }\n\n /// @notice Allows the Governance to withdraw unmint fees accumulated by\n /// `VendingMachine`.\n /// @param recipient The address receiving the fees\n /// @param amount The amount of fees in TBTC v2 to withdraw\n function withdrawFees(address recipient, uint256 amount)\n external\n onlyOwner\n {\n tbtcV2.safeTransfer(recipient, amount);\n }\n\n /// @notice Initiates unmint fee update process. The update process needs to\n /// be finalized with a call to `finalizeUnmintFeeUpdate` function\n /// after the `GOVERNANCE_DELAY` passes. Only unmint fee update\n /// initiator role can initiate the update.\n /// @param _newUnmintFee The new unmint fee\n function initiateUnmintFeeUpdate(uint256 _newUnmintFee)\n external\n only(unmintFeeUpdateInitiator)\n {\n /* solhint-disable-next-line not-rely-on-time */\n emit UnmintFeeUpdateInitiated(_newUnmintFee, block.timestamp);\n newUnmintFee = _newUnmintFee;\n /* solhint-disable-next-line not-rely-on-time */\n unmintFeeUpdateInitiatedTimestamp = block.timestamp;\n }\n\n /// @notice Allows the contract owner to finalize unmint fee update process.\n /// The update process needs to be first initiated with a call to\n /// `initiateUnmintFeeUpdate` and the `GOVERNANCE_DELAY` needs to\n /// pass.\n function finalizeUnmintFeeUpdate()\n external\n onlyOwner\n onlyAfterGovernanceDelay(unmintFeeUpdateInitiatedTimestamp)\n {\n emit UnmintFeeUpdated(newUnmintFee);\n unmintFee = newUnmintFee;\n newUnmintFee = 0;\n unmintFeeUpdateInitiatedTimestamp = 0;\n }\n\n /// @notice Initiates vending machine upgrade process. The upgrade process\n /// needs to be finalized with a call to\n /// `finalizeVendingMachineUpgrade` function after the\n /// `GOVERNANCE_DELAY` passes. Only vending machine upgrade\n /// initiator role can initiate the upgrade.\n /// @param _newVendingMachine The new vending machine address\n function initiateVendingMachineUpgrade(address _newVendingMachine)\n external\n only(vendingMachineUpgradeInitiator)\n {\n require(\n _newVendingMachine != address(0),\n \"New VendingMachine cannot be zero address\"\n );\n\n emit VendingMachineUpgradeInitiated(\n _newVendingMachine,\n /* solhint-disable-next-line not-rely-on-time */\n block.timestamp\n );\n newVendingMachine = _newVendingMachine;\n /* solhint-disable-next-line not-rely-on-time */\n vendingMachineUpgradeInitiatedTimestamp = block.timestamp;\n }\n\n /// @notice Allows the contract owner to finalize vending machine upgrade\n /// process. The upgrade process needs to be first initiated with a\n /// call to `initiateVendingMachineUpgrade` and the `GOVERNANCE_DELAY`\n /// needs to pass. Once the upgrade is finalized, the new vending\n /// machine will become an owner of TBTC v2 token and all TBTC v1\n /// held by this contract will be transferred to the new vending\n /// machine.\n function finalizeVendingMachineUpgrade()\n external\n onlyOwner\n onlyAfterGovernanceDelay(vendingMachineUpgradeInitiatedTimestamp)\n {\n emit VendingMachineUpgraded(newVendingMachine);\n //slither-disable-next-line reentrancy-no-eth\n tbtcV2.transferOwnership(newVendingMachine);\n tbtcV1.safeTransfer(newVendingMachine, tbtcV1.balanceOf(address(this)));\n newVendingMachine = address(0);\n vendingMachineUpgradeInitiatedTimestamp = 0;\n }\n\n /// @notice Transfers unmint fee update initiator role to another address.\n /// Can be called only by the current unmint fee update initiator.\n /// @param newInitiator The new unmint fee update initiator\n function transferUnmintFeeUpdateInitiatorRole(address newInitiator)\n external\n only(unmintFeeUpdateInitiator)\n {\n require(\n newInitiator != address(0),\n \"New initiator must not be zero address\"\n );\n unmintFeeUpdateInitiator = newInitiator;\n }\n\n /// @notice Transfers vending machine upgrade initiator role to another\n /// address. Can be called only by the current vending machine\n /// upgrade initiator.\n /// @param newInitiator The new vending machine upgrade initiator\n function transferVendingMachineUpgradeInitiatorRole(address newInitiator)\n external\n only(vendingMachineUpgradeInitiator)\n {\n require(\n newInitiator != address(0),\n \"New initiator must not be zero address\"\n );\n vendingMachineUpgradeInitiator = newInitiator;\n }\n\n /// @notice Get the remaining time that needs to pass until unmint fee\n /// update can be finalized by the Governance. If the update has\n /// not been initiated, the function reverts.\n function getRemainingUnmintFeeUpdateTime() external view returns (uint256) {\n return\n GovernanceUtils.getRemainingGovernanceDelay(\n unmintFeeUpdateInitiatedTimestamp,\n GOVERNANCE_DELAY\n );\n }\n\n /// @notice Get the remaining time that needs to pass until vending machine\n /// upgrade can be finalized by the Governance. If the upgrade has\n /// not been initiated, the function reverts.\n function getRemainingVendingMachineUpgradeTime()\n external\n view\n returns (uint256)\n {\n return\n GovernanceUtils.getRemainingGovernanceDelay(\n vendingMachineUpgradeInitiatedTimestamp,\n GOVERNANCE_DELAY\n );\n }\n\n /// @notice Calculates the fee that needs to be paid to the `VendingMachine`\n /// to unmint the given amount of TBTC v2 back into TBTC v1.\n function unmintFeeFor(uint256 amount) public view returns (uint256) {\n return (amount * unmintFee) / FLOATING_POINT_DIVISOR;\n }\n\n function _mint(address tokenOwner, uint256 amount) internal {\n emit Minted(tokenOwner, amount);\n tbtcV1.safeTransferFrom(tokenOwner, address(this), amount);\n tbtcV2.mint(tokenOwner, amount);\n }\n}\n" + }, + "contracts/bridge/VendingMachineV2.sol": { + "content": "// SPDX-License-Identifier: GPL-3.0-only\n\npragma solidity 0.8.17;\n\nimport \"@openzeppelin/contracts/access/Ownable.sol\";\nimport \"@openzeppelin/contracts/token/ERC20/IERC20.sol\";\nimport \"@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol\";\n\nimport \"../token/TBTC.sol\";\n\n/// @title VendingMachineV2\n/// @notice VendingMachineV2 is used to exchange tBTC v1 to tBTC v2 in a 1:1\n/// ratio during the process of tBTC v1 bridge sunsetting. The redeemer\n/// selected by the DAO based on the \"TIP-027b tBTC v1: The Sunsetting\"\n/// proposal will deposit tBTC v2 tokens into VendingMachineV2 so that\n/// outstanding tBTC v1 token owners can upgrade to tBTC v2 tokens.\n/// The redeemer will withdraw the tBTC v1 tokens deposited into the\n/// contract to perform tBTC v1 redemptions.\n/// The redeemer may decide to withdraw their deposited tBTC v2 at any\n/// moment in time. The amount withdrawable is lower than the amount\n/// deposited in case tBTC v1 was exchanged for tBTC v2.\n/// This contract is owned by the redeemer.\ncontract VendingMachineV2 is Ownable {\n using SafeERC20 for IERC20;\n using SafeERC20 for TBTC;\n\n IERC20 public immutable tbtcV1;\n TBTC public immutable tbtcV2;\n\n event Exchanged(address indexed to, uint256 amount);\n event Deposited(address from, uint256 amount);\n event Withdrawn(address token, address to, uint256 amount);\n\n constructor(IERC20 _tbtcV1, TBTC _tbtcV2) {\n tbtcV1 = _tbtcV1;\n tbtcV2 = _tbtcV2;\n }\n\n /// @notice Exchange tBTC v1 for tBTC v2 in a 1:1 ratio.\n /// The caller needs to have at least `amount` of tBTC v1 balance\n /// approved for transfer to the `VendingMachineV2` before calling\n /// this function.\n /// @param amount The amount of tBTC v1 to exchange for tBTC v2.\n function exchange(uint256 amount) external {\n _exchange(msg.sender, amount);\n }\n\n /// @notice Exchange tBTC v1 for tBTC v2 in a 1:1 ratio.\n /// The caller needs to have at least `amount` of tBTC v1 balance\n /// approved for transfer to the `VendingMachineV2` before calling\n /// this function.\n /// @dev This function is a shortcut for `approve` + `exchange`. Only tBTC\n /// v1 token caller is allowed and only tBTC v1 is allowed as a token\n /// to transfer.\n /// @param from tBTC v1 token holder exchanging tBTC v1 to tBTC v2.\n /// @param amount The amount of tBTC v1 to exchange for tBTC v2.\n /// @param token tBTC v1 token address.\n function receiveApproval(\n address from,\n uint256 amount,\n address token,\n bytes calldata\n ) external {\n require(token == address(tbtcV1), \"Token is not tBTC v1\");\n require(msg.sender == address(tbtcV1), \"Only tBTC v1 caller allowed\");\n _exchange(from, amount);\n }\n\n /// @notice Allows to deposit tBTC v2 tokens to the contract.\n /// VendingMachineV2 can not mint tBTC v2 tokens so tBTC v2 needs\n /// to be deposited into the contract so that tBTC v1 to tBTC v2\n /// exchange can happen.\n /// The caller needs to have at least `amount` of tBTC v2 balance\n /// approved for transfer to the `VendingMachineV2` before calling\n /// this function.\n /// @dev This function is for the redeemer and tBTC v1 operators. This is\n /// NOT a function for tBTC v1 token holders.\n /// @param amount The amount of tBTC v2 to deposit into the contract.\n function depositTbtcV2(uint256 amount) external {\n emit Deposited(msg.sender, amount);\n tbtcV2.safeTransferFrom(msg.sender, address(this), amount);\n }\n\n /// @notice Allows the contract owner to withdraw tokens. This function is\n /// used in two cases: 1) when the redeemer wants to redeem tBTC v1\n /// tokens to perform tBTC v2 redemptions; 2) when the deadline for\n /// tBTC v1 -> tBTC v2 exchange passed and the redeemer wants their\n /// tBTC v2 back.\n /// @dev This function is for the redeemer. This is NOT a function for\n /// tBTC v1 token holders.\n /// @param token The address of a token to withdraw.\n /// @param recipient The address which should receive withdrawn tokens.\n /// @param amount The amount to withdraw.\n function withdrawFunds(\n IERC20 token,\n address recipient,\n uint256 amount\n ) external onlyOwner {\n emit Withdrawn(address(token), recipient, amount);\n token.safeTransfer(recipient, amount);\n }\n\n function _exchange(address tokenOwner, uint256 amount) internal {\n require(\n tbtcV2.balanceOf(address(this)) >= amount,\n \"Not enough tBTC v2 available in the Vending Machine\"\n );\n\n emit Exchanged(tokenOwner, amount);\n tbtcV1.safeTransferFrom(tokenOwner, address(this), amount);\n\n tbtcV2.safeTransfer(tokenOwner, amount);\n }\n}\n" + }, + "contracts/bridge/VendingMachineV3.sol": { + "content": "// SPDX-License-Identifier: GPL-3.0-only\n\npragma solidity 0.8.17;\n\nimport \"@openzeppelin/contracts/access/Ownable.sol\";\nimport \"@openzeppelin/contracts/token/ERC20/IERC20.sol\";\nimport \"@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol\";\n\nimport \"../token/TBTC.sol\";\n\n/// @title VendingMachineV3\n/// @notice VendingMachineV3 is used to exchange tBTC v1 to tBTC v2 in a 1:1\n/// ratio after the tBTC v1 bridge sunsetting is completed. Since\n/// tBTC v1 bridge is no longer working, tBTC v1 tokens can not be used\n/// to perform BTC redemptions. This contract allows tBTC v1 owners to\n/// upgrade to tBTC v2 without any deadline. This way, tBTC v1 tokens\n/// left on the market are always backed by Bitcoin. The governance will\n/// deposit tBTC v2 into the contract in the amount equal to tBTC v1\n/// supply. The governance is allowed to withdraw tBTC v2 only if tBTC\n/// v2 left in this contract is enough to cover the upgrade of all tBTC\n/// v1 left on the market. This contract is owned by the governance.\ncontract VendingMachineV3 is Ownable {\n using SafeERC20 for IERC20;\n using SafeERC20 for TBTC;\n\n IERC20 public immutable tbtcV1;\n TBTC public immutable tbtcV2;\n\n event Exchanged(address indexed to, uint256 amount);\n event Deposited(address from, uint256 amount);\n event TbtcV2Withdrawn(address to, uint256 amount);\n event FundsRecovered(address token, address to, uint256 amount);\n\n constructor(IERC20 _tbtcV1, TBTC _tbtcV2) {\n tbtcV1 = _tbtcV1;\n tbtcV2 = _tbtcV2;\n }\n\n /// @notice Exchange tBTC v1 for tBTC v2 in a 1:1 ratio.\n /// The caller needs to have at least `amount` of tBTC v1 balance\n /// approved for transfer to the `VendingMachineV3` before calling\n /// this function.\n /// @param amount The amount of tBTC v1 to exchange for tBTC v2.\n function exchange(uint256 amount) external {\n _exchange(msg.sender, amount);\n }\n\n /// @notice Exchange tBTC v1 for tBTC v2 in a 1:1 ratio.\n /// The caller needs to have at least `amount` of tBTC v1 balance\n /// approved for transfer to the `VendingMachineV3` before calling\n /// this function.\n /// @dev This function is a shortcut for `approve` + `exchange`. Only tBTC\n /// v1 caller is allowed and only tBTC v1 is allowed as a token to\n /// transfer.\n /// @param from tBTC v1 token holder exchanging tBTC v1 to tBTC v2.\n /// @param amount The amount of tBTC v1 to exchange for tBTC v2.\n /// @param token tBTC v1 token address.\n function receiveApproval(\n address from,\n uint256 amount,\n address token,\n bytes calldata\n ) external {\n require(token == address(tbtcV1), \"Token is not tBTC v1\");\n require(msg.sender == address(tbtcV1), \"Only tBTC v1 caller allowed\");\n _exchange(from, amount);\n }\n\n /// @notice Allows to deposit tBTC v2 tokens to the contract.\n /// `VendingMachineV3` can not mint tBTC v2 tokens so tBTC v2 needs\n /// to be deposited into the contract so that tBTC v1 to tBTC v2\n /// exchange can happen.\n /// The caller needs to have at least `amount` of tBTC v2 balance\n /// approved for transfer to the `VendingMachineV3` before calling\n /// this function.\n /// @dev This function is for the redeemer and tBTC v1 operators. This is\n /// NOT a function for tBTC v1 token holders.\n /// @param amount The amount of tBTC v2 to deposit into the contract.\n function depositTbtcV2(uint256 amount) external {\n emit Deposited(msg.sender, amount);\n tbtcV2.safeTransferFrom(msg.sender, address(this), amount);\n }\n\n /// @notice Allows the governance to withdraw tBTC v2 deposited into this\n /// contract. The governance is allowed to withdraw tBTC v2\n /// only if tBTC v2 left in this contract is enough to cover the\n /// upgrade of all tBTC v1 left on the market.\n /// @param recipient The address which should receive withdrawn tokens.\n /// @param amount The amount to withdraw.\n function withdrawTbtcV2(address recipient, uint256 amount)\n external\n onlyOwner\n {\n require(\n tbtcV1.totalSupply() <= tbtcV2.balanceOf(address(this)) - amount,\n \"tBTC v1 must not be left unbacked\"\n );\n\n emit TbtcV2Withdrawn(recipient, amount);\n tbtcV2.safeTransfer(recipient, amount);\n }\n\n /// @notice Allows the governance to recover ERC20 sent to this contract\n /// by mistake or tBTC v1 locked in the contract to exchange to\n /// tBTC v2. No tBTC v2 can be withdrawn using this function.\n /// @param token The address of a token to recover.\n /// @param recipient The address which should receive recovered tokens.\n /// @param amount The amount to recover.\n function recoverFunds(\n IERC20 token,\n address recipient,\n uint256 amount\n ) external onlyOwner {\n require(\n address(token) != address(tbtcV2),\n \"tBTC v2 tokens can not be recovered, use withdrawTbtcV2 instead\"\n );\n\n emit FundsRecovered(address(token), recipient, amount);\n token.safeTransfer(recipient, amount);\n }\n\n function _exchange(address tokenOwner, uint256 amount) internal {\n require(\n tbtcV2.balanceOf(address(this)) >= amount,\n \"Not enough tBTC v2 available in the Vending Machine\"\n );\n\n emit Exchanged(tokenOwner, amount);\n tbtcV1.safeTransferFrom(tokenOwner, address(this), amount);\n\n tbtcV2.safeTransfer(tokenOwner, amount);\n }\n}\n" + }, + "contracts/bridge/WalletCoordinator.sol": { + "content": "// SPDX-License-Identifier: GPL-3.0-only\n\n// ██████████████ ▐████▌ ██████████████\n// ██████████████ ▐████▌ ██████████████\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ██████████████ ▐████▌ ██████████████\n// ██████████████ ▐████▌ ██████████████\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n\npragma solidity 0.8.17;\n\nimport {BTCUtils} from \"@keep-network/bitcoin-spv-sol/contracts/BTCUtils.sol\";\nimport {BytesLib} from \"@keep-network/bitcoin-spv-sol/contracts/BytesLib.sol\";\nimport \"@keep-network/random-beacon/contracts/Reimbursable.sol\";\nimport \"@keep-network/random-beacon/contracts/ReimbursementPool.sol\";\n\nimport \"@openzeppelin/contracts-upgradeable/access/OwnableUpgradeable.sol\";\n\nimport \"./BitcoinTx.sol\";\nimport \"./Bridge.sol\";\nimport \"./Deposit.sol\";\nimport \"./Redemption.sol\";\nimport \"./Wallets.sol\";\n\n/// @title Wallet coordinator.\n/// @notice The wallet coordinator contract aims to facilitate the coordination\n/// of the off-chain wallet members during complex multi-chain wallet\n/// operations like deposit sweeping, redemptions, or moving funds.\n/// Such processes involve various moving parts and many steps that each\n/// individual wallet member must do. Given the distributed nature of\n/// the off-chain wallet software, full off-chain implementation is\n/// challenging and prone to errors, especially byzantine faults.\n/// This contract provides a single and trusted on-chain coordination\n/// point thus taking the riskiest part out of the off-chain software.\n/// The off-chain wallet members can focus on the core tasks and do not\n/// bother about electing a trusted coordinator or aligning internal\n/// states using complex consensus algorithms.\ncontract WalletCoordinator is OwnableUpgradeable, Reimbursable {\n using BTCUtils for bytes;\n using BytesLib for bytes;\n\n /// @notice Represents wallet action:\n enum WalletAction {\n /// @dev The wallet does not perform any action.\n Idle,\n /// @dev The wallet is executing heartbeat.\n Heartbeat,\n /// @dev The wallet is handling a deposit sweep action.\n DepositSweep,\n /// @dev The wallet is handling a redemption action.\n Redemption,\n /// @dev The wallet is handling a moving funds action.\n MovingFunds,\n /// @dev The wallet is handling a moved funds sweep action.\n MovedFundsSweep\n }\n\n /// @notice Holds information about a wallet time lock.\n struct WalletLock {\n /// @notice A UNIX timestamp defining the moment until which the wallet\n /// is locked and cannot receive new proposals. The value of 0\n /// means the wallet is not locked and can receive a proposal\n /// at any time.\n uint32 expiresAt;\n /// @notice The wallet action being the cause of the lock.\n WalletAction cause;\n }\n\n /// @notice Helper structure representing a deposit sweep proposal.\n struct DepositSweepProposal {\n // 20-byte public key hash of the target wallet.\n bytes20 walletPubKeyHash;\n // Deposits that should be part of the sweep.\n DepositKey[] depositsKeys;\n // Proposed BTC fee for the entire transaction.\n uint256 sweepTxFee;\n // Array containing the reveal blocks of each deposit. This information\n // strongly facilitates the off-chain processing. Using those blocks,\n // wallet operators can quickly fetch corresponding Bridge.DepositRevealed\n // events carrying deposit data necessary to perform proposal validation.\n // This field is not explicitly validated within the validateDepositSweepProposal\n // function because if something is wrong here the off-chain wallet\n // operators will fail anyway as they won't be able to gather deposit\n // data necessary to perform the on-chain validation using the\n // validateDepositSweepProposal function.\n uint256[] depositsRevealBlocks;\n }\n\n /// @notice Helper structure representing a plain-text deposit key.\n /// Each deposit can be identified by their 32-byte funding\n /// transaction hash (Bitcoin internal byte order) an the funding\n /// output index (0-based).\n /// @dev Do not confuse this structure with the deposit key used within the\n /// Bridge contract to store deposits. Here we have the plain-text\n /// components of the key while the Bridge uses a uint representation of\n /// keccak256(fundingTxHash | fundingOutputIndex) for gas efficiency.\n struct DepositKey {\n bytes32 fundingTxHash;\n uint32 fundingOutputIndex;\n }\n\n /// @notice Helper structure holding deposit extra data required during\n /// deposit sweep proposal validation. Basically, this structure\n /// is a combination of BitcoinTx.Info and relevant parts of\n /// Deposit.DepositRevealInfo.\n /// @dev These data can be pulled from respective `DepositRevealed` events\n /// emitted by the `Bridge.revealDeposit` function. The `fundingTx`\n /// field must be taken directly from the Bitcoin chain, using the\n /// `DepositRevealed.fundingTxHash` as transaction identifier.\n struct DepositExtraInfo {\n BitcoinTx.Info fundingTx;\n bytes8 blindingFactor;\n bytes20 walletPubKeyHash;\n bytes20 refundPubKeyHash;\n bytes4 refundLocktime;\n }\n\n /// @notice Helper structure representing a redemption proposal.\n struct RedemptionProposal {\n // 20-byte public key hash of the target wallet.\n bytes20 walletPubKeyHash;\n // Array of the redeemers' output scripts that should be part of\n // the redemption. Each output script MUST BE prefixed by its byte\n // length, i.e. passed in the exactly same format as during the\n // `Bridge.requestRedemption` transaction.\n bytes[] redeemersOutputScripts;\n // Proposed BTC fee for the entire transaction.\n uint256 redemptionTxFee;\n }\n\n /// @notice Mapping that holds addresses allowed to submit proposals and\n /// request heartbeats.\n mapping(address => bool) public isCoordinator;\n\n /// @notice Mapping that holds wallet time locks. The key is a 20-byte\n /// wallet public key hash.\n mapping(bytes20 => WalletLock) public walletLock;\n\n /// @notice Handle to the Bridge contract.\n Bridge public bridge;\n\n /// @notice Determines the wallet heartbeat request validity time. In other\n /// words, this is the worst-case time for a wallet heartbeat\n /// during which the wallet is busy and canot take other actions.\n /// This is also the duration of the time lock applied to the wallet\n /// once a new heartbeat request is submitted.\n ///\n /// For example, if a deposit sweep proposal was submitted at\n /// 2 pm and heartbeatRequestValidity is 1 hour, the next request or\n /// proposal (of any type) can be submitted after 3 pm.\n uint32 public heartbeatRequestValidity;\n\n /// @notice Gas that is meant to balance the heartbeat request overall cost.\n /// Can be updated by the owner based on the current conditions.\n uint32 public heartbeatRequestGasOffset;\n\n /// @notice Determines the deposit sweep proposal validity time. In other\n /// words, this is the worst-case time for a deposit sweep during\n /// which the wallet is busy and cannot take another actions. This\n /// is also the duration of the time lock applied to the wallet\n /// once a new deposit sweep proposal is submitted.\n ///\n /// For example, if a deposit sweep proposal was submitted at\n /// 2 pm and depositSweepProposalValidity is 4 hours, the next\n /// proposal (of any type) can be submitted after 6 pm.\n uint32 public depositSweepProposalValidity;\n\n /// @notice The minimum time that must elapse since the deposit reveal\n /// before a deposit becomes eligible for a deposit sweep.\n ///\n /// For example, if a deposit was revealed at 9 am and depositMinAge\n /// is 2 hours, the deposit is eligible for sweep after 11 am.\n ///\n /// @dev Forcing deposit minimum age ensures block finality for Ethereum.\n /// In the happy path case, i.e. where the deposit is revealed immediately\n /// after being broadcast on the Bitcoin network, the minimum age\n /// check also ensures block finality for Bitcoin.\n uint32 public depositMinAge;\n\n /// @notice Each deposit can be technically swept until it reaches its\n /// refund timestamp after which it can be taken back by the depositor.\n /// However, allowing the wallet to sweep deposits that are close\n /// to their refund timestamp may cause a race between the wallet\n /// and the depositor. In result, the wallet may sign an invalid\n /// sweep transaction that aims to sweep an already refunded deposit.\n /// Such tx signature may be used to create an undefeatable fraud\n /// challenge against the wallet. In order to mitigate that problem,\n /// this parameter determines a safety margin that puts the latest\n /// moment a deposit can be swept far before the point after which\n /// the deposit becomes refundable.\n ///\n /// For example, if a deposit becomes refundable after 8 pm and\n /// depositRefundSafetyMargin is 6 hours, the deposit is valid for\n /// for a sweep only before 2 pm.\n uint32 public depositRefundSafetyMargin;\n\n /// @notice The maximum count of deposits that can be swept within a\n /// single sweep.\n uint16 public depositSweepMaxSize;\n\n /// @notice Gas that is meant to balance the deposit sweep proposal\n /// submission overall cost. Can be updated by the owner based on\n /// the current conditions.\n uint32 public depositSweepProposalSubmissionGasOffset;\n\n /// @notice Determines the redemption proposal validity time. In other\n /// words, this is the worst-case time for a redemption during\n /// which the wallet is busy and cannot take another actions. This\n /// is also the duration of the time lock applied to the wallet\n /// once a new redemption proposal is submitted.\n ///\n /// For example, if a redemption proposal was submitted at\n /// 2 pm and redemptionProposalValidity is 2 hours, the next\n /// proposal (of any type) can be submitted after 4 pm.\n uint32 public redemptionProposalValidity;\n\n /// @notice The minimum time that must elapse since the redemption request\n /// creation before a request becomes eligible for a processing.\n ///\n /// For example, if a request was created at 9 am and\n /// redemptionRequestMinAge is 2 hours, the request is eligible for\n /// processing after 11 am.\n ///\n /// @dev Forcing request minimum age ensures block finality for Ethereum.\n uint32 public redemptionRequestMinAge;\n\n /// @notice Each redemption request can be technically handled until it\n /// reaches its timeout timestamp after which it can be reported\n /// as timed out. However, allowing the wallet to handle requests\n /// that are close to their timeout timestamp may cause a race\n /// between the wallet and the redeemer. In result, the wallet may\n /// redeem the requested funds even though the redeemer already\n /// received back their tBTC (locked during redemption request) upon\n /// reporting the request timeout. In effect, the redeemer may end\n /// out with both tBTC and redeemed BTC in their hands which has\n /// a negative impact on the tBTC <-> BTC peg. In order to mitigate\n /// that problem, this parameter determines a safety margin that\n /// puts the latest moment a request can be handled far before the\n /// point after which the request can be reported as timed out.\n ///\n /// For example, if a request times out after 8 pm and\n /// redemptionRequestTimeoutSafetyMargin is 2 hours, the request is\n /// valid for processing only before 6 pm.\n uint32 public redemptionRequestTimeoutSafetyMargin;\n\n /// @notice The maximum count of redemption requests that can be processed\n /// within a single redemption.\n uint16 public redemptionMaxSize;\n\n /// @notice Gas that is meant to balance the redemption proposal\n /// submission overall cost. Can be updated by the owner based on\n /// the current conditions.\n uint32 public redemptionProposalSubmissionGasOffset;\n\n event CoordinatorAdded(address indexed coordinator);\n\n event CoordinatorRemoved(address indexed coordinator);\n\n event WalletManuallyUnlocked(bytes20 indexed walletPubKeyHash);\n\n event HeartbeatRequestParametersUpdated(\n uint32 heartbeatRequestValidity,\n uint32 heartbeatRequestGasOffset\n );\n\n event HeartbeatRequestSubmitted(\n bytes20 walletPubKeyHash,\n bytes message,\n address indexed coordinator\n );\n\n event DepositSweepProposalParametersUpdated(\n uint32 depositSweepProposalValidity,\n uint32 depositMinAge,\n uint32 depositRefundSafetyMargin,\n uint16 depositSweepMaxSize,\n uint32 depositSweepProposalSubmissionGasOffset\n );\n\n event DepositSweepProposalSubmitted(\n DepositSweepProposal proposal,\n address indexed coordinator\n );\n\n event RedemptionProposalParametersUpdated(\n uint32 redemptionProposalValidity,\n uint32 redemptionRequestMinAge,\n uint32 redemptionRequestTimeoutSafetyMargin,\n uint16 redemptionMaxSize,\n uint32 redemptionProposalSubmissionGasOffset\n );\n\n event RedemptionProposalSubmitted(\n RedemptionProposal proposal,\n address indexed coordinator\n );\n\n modifier onlyCoordinator() {\n require(isCoordinator[msg.sender], \"Caller is not a coordinator\");\n _;\n }\n\n modifier onlyAfterWalletLock(bytes20 walletPubKeyHash) {\n require(\n /* solhint-disable-next-line not-rely-on-time */\n block.timestamp > walletLock[walletPubKeyHash].expiresAt,\n \"Wallet locked\"\n );\n _;\n }\n\n modifier onlyReimbursableAdmin() override {\n require(owner() == msg.sender, \"Caller is not the owner\");\n _;\n }\n\n function initialize(Bridge _bridge) external initializer {\n __Ownable_init();\n\n bridge = _bridge;\n // Pre-fetch addresses to save gas later.\n (, , , reimbursementPool) = _bridge.contractReferences();\n\n heartbeatRequestValidity = 1 hours;\n heartbeatRequestGasOffset = 10_000;\n\n depositSweepProposalValidity = 4 hours;\n depositMinAge = 2 hours;\n depositRefundSafetyMargin = 24 hours;\n depositSweepMaxSize = 5;\n depositSweepProposalSubmissionGasOffset = 20_000; // optimized for 10 inputs\n\n redemptionProposalValidity = 2 hours;\n redemptionRequestMinAge = 600; // 10 minutes or ~50 blocks.\n redemptionRequestTimeoutSafetyMargin = 2 hours;\n redemptionMaxSize = 20;\n redemptionProposalSubmissionGasOffset = 20_000;\n }\n\n /// @notice Adds the given address to the set of coordinator addresses.\n /// @param coordinator Address of the new coordinator.\n /// @dev Requirements:\n /// - The caller must be the owner,\n /// - The `coordinator` must not be an existing coordinator.\n function addCoordinator(address coordinator) external onlyOwner {\n require(\n !isCoordinator[coordinator],\n \"This address is already a coordinator\"\n );\n isCoordinator[coordinator] = true;\n emit CoordinatorAdded(coordinator);\n }\n\n /// @notice Removes the given address from the set of coordinator addresses.\n /// @param coordinator Address of the existing coordinator.\n /// @dev Requirements:\n /// - The caller must be the owner,\n /// - The `coordinator` must be an existing coordinator.\n function removeCoordinator(address coordinator) external onlyOwner {\n require(\n isCoordinator[coordinator],\n \"This address is not a coordinator\"\n );\n delete isCoordinator[coordinator];\n emit CoordinatorRemoved(coordinator);\n }\n\n /// @notice Allows to unlock the given wallet before their time lock expires.\n /// This function should be used in exceptional cases where\n /// something went wrong and there is a need to unlock the wallet\n /// without waiting.\n /// @param walletPubKeyHash 20-byte public key hash of the wallet\n /// @dev Requirements:\n /// - The caller must be the owner.\n function unlockWallet(bytes20 walletPubKeyHash) external onlyOwner {\n // Just in case, allow the owner to unlock the wallet earlier.\n walletLock[walletPubKeyHash] = WalletLock(0, WalletAction.Idle);\n emit WalletManuallyUnlocked(walletPubKeyHash);\n }\n\n /// @notice Updates parameters related to heartbeat request.\n /// @param _heartbeatRequestValidity The new value of `heartbeatRequestValidity`.\n /// @param _heartbeatRequestGasOffset The new value of `heartbeatRequestGasOffset`.\n /// @dev Requirements:\n /// - The caller must be the owner.\n function updateHeartbeatRequestParameters(\n uint32 _heartbeatRequestValidity,\n uint32 _heartbeatRequestGasOffset\n ) external onlyOwner {\n heartbeatRequestValidity = _heartbeatRequestValidity;\n heartbeatRequestGasOffset = _heartbeatRequestGasOffset;\n emit HeartbeatRequestParametersUpdated(\n _heartbeatRequestValidity,\n _heartbeatRequestGasOffset\n );\n }\n\n /// @notice Updates parameters related to deposit sweep proposal.\n /// @param _depositSweepProposalValidity The new value of `depositSweepProposalValidity`.\n /// @param _depositMinAge The new value of `depositMinAge`.\n /// @param _depositRefundSafetyMargin The new value of `depositRefundSafetyMargin`.\n /// @param _depositSweepMaxSize The new value of `depositSweepMaxSize`.\n /// @dev Requirements:\n /// - The caller must be the owner.\n function updateDepositSweepProposalParameters(\n uint32 _depositSweepProposalValidity,\n uint32 _depositMinAge,\n uint32 _depositRefundSafetyMargin,\n uint16 _depositSweepMaxSize,\n uint32 _depositSweepProposalSubmissionGasOffset\n ) external onlyOwner {\n depositSweepProposalValidity = _depositSweepProposalValidity;\n depositMinAge = _depositMinAge;\n depositRefundSafetyMargin = _depositRefundSafetyMargin;\n depositSweepMaxSize = _depositSweepMaxSize;\n depositSweepProposalSubmissionGasOffset = _depositSweepProposalSubmissionGasOffset;\n\n emit DepositSweepProposalParametersUpdated(\n _depositSweepProposalValidity,\n _depositMinAge,\n _depositRefundSafetyMargin,\n _depositSweepMaxSize,\n _depositSweepProposalSubmissionGasOffset\n );\n }\n\n /// @notice Submits a heartbeat request from the wallet. Locks the wallet\n /// for a specific time, equal to the request validity period.\n /// This function validates the proposed heartbeat messge to see\n /// if it matches the heartbeat format expected by the Bridge.\n /// @param walletPubKeyHash 20-byte public key hash of the wallet that is\n /// supposed to execute the heartbeat.\n /// @param message The proposed heartbeat message for the wallet to sign.\n /// @dev Requirements:\n /// - The caller is a coordinator,\n /// - The wallet is not time-locked,\n /// - The message to sign is a valid heartbeat message.\n function requestHeartbeat(bytes20 walletPubKeyHash, bytes calldata message)\n public\n onlyCoordinator\n onlyAfterWalletLock(walletPubKeyHash)\n {\n require(\n Heartbeat.isValidHeartbeatMessage(message),\n \"Not a valid heartbeat message\"\n );\n\n walletLock[walletPubKeyHash] = WalletLock(\n /* solhint-disable-next-line not-rely-on-time */\n uint32(block.timestamp) + heartbeatRequestValidity,\n WalletAction.Heartbeat\n );\n\n emit HeartbeatRequestSubmitted(walletPubKeyHash, message, msg.sender);\n }\n\n /// @notice Wraps `requestHeartbeat` call and reimburses the caller's\n /// transaction cost.\n /// @dev See `requestHeartbeat` function documentation.\n function requestHeartbeatWithReimbursement(\n bytes20 walletPubKeyHash,\n bytes calldata message\n ) external {\n uint256 gasStart = gasleft();\n\n requestHeartbeat(walletPubKeyHash, message);\n\n reimbursementPool.refund(\n (gasStart - gasleft()) + heartbeatRequestGasOffset,\n msg.sender\n );\n }\n\n /// @notice Submits a deposit sweep proposal. Locks the target wallet\n /// for a specific time, equal to the proposal validity period.\n /// This function does not store the proposal in the state but\n /// just emits an event that serves as a guiding light for wallet\n /// off-chain members. Wallet members are supposed to validate\n /// the proposal on their own, before taking any action.\n /// @param proposal The deposit sweep proposal\n /// @dev Requirements:\n /// - The caller is a coordinator,\n /// - The wallet is not time-locked.\n function submitDepositSweepProposal(DepositSweepProposal calldata proposal)\n public\n onlyCoordinator\n onlyAfterWalletLock(proposal.walletPubKeyHash)\n {\n walletLock[proposal.walletPubKeyHash] = WalletLock(\n /* solhint-disable-next-line not-rely-on-time */\n uint32(block.timestamp) + depositSweepProposalValidity,\n WalletAction.DepositSweep\n );\n\n emit DepositSweepProposalSubmitted(proposal, msg.sender);\n }\n\n /// @notice Wraps `submitDepositSweepProposal` call and reimburses the\n /// caller's transaction cost.\n /// @dev See `submitDepositSweepProposal` function documentation.\n function submitDepositSweepProposalWithReimbursement(\n DepositSweepProposal calldata proposal\n ) external {\n uint256 gasStart = gasleft();\n\n submitDepositSweepProposal(proposal);\n\n reimbursementPool.refund(\n (gasStart - gasleft()) + depositSweepProposalSubmissionGasOffset,\n msg.sender\n );\n }\n\n /// @notice View function encapsulating the main rules of a valid deposit\n /// sweep proposal. This function is meant to facilitate the off-chain\n /// validation of the incoming proposals. Thanks to it, most\n /// of the work can be done using a single readonly contract call.\n /// Worth noting, the validation done here is not exhaustive as some\n /// conditions may not be verifiable within the on-chain function or\n /// checking them may be easier on the off-chain side. For example,\n /// this function does not check the SPV proofs and confirmations of\n /// the deposit funding transactions as this would require an\n /// integration with the difficulty relay that greatly increases\n /// complexity. Instead of that, each off-chain wallet member is\n /// supposed to do that check on their own.\n /// @param proposal The sweeping proposal to validate.\n /// @param depositsExtraInfo Deposits extra data required to perform the validation.\n /// @return True if the proposal is valid. Reverts otherwise.\n /// @dev Requirements:\n /// - The target wallet must be in the Live state,\n /// - The number of deposits included in the sweep must be in\n /// the range [1, `depositSweepMaxSize`],\n /// - The length of `depositsExtraInfo` array must be equal to the\n /// length of `proposal.depositsKeys`, i.e. each deposit must\n /// have exactly one set of corresponding extra data,\n /// - The proposed sweep tx fee must be grater than zero,\n /// - The proposed maximum per-deposit sweep tx fee must be lesser than\n /// or equal the maximum fee allowed by the Bridge (`Bridge.depositTxMaxFee`),\n /// - Each deposit must be revealed to the Bridge,\n /// - Each deposit must be old enough, i.e. at least `depositMinAge`\n /// elapsed since their reveal time,\n /// - Each deposit must not be swept yet,\n /// - Each deposit must have valid extra data (see `validateDepositExtraInfo`),\n /// - Each deposit must have the refund safety margin preserved,\n /// - Each deposit must be controlled by the same wallet,\n /// - Each deposit must target the same vault,\n /// - Each deposit must be unique.\n ///\n /// The following off-chain validation must be performed as a bare minimum:\n /// - Inputs used for the sweep transaction have enough Bitcoin confirmations,\n /// - Deposits revealed to the Bridge have enough Ethereum confirmations.\n function validateDepositSweepProposal(\n DepositSweepProposal calldata proposal,\n DepositExtraInfo[] calldata depositsExtraInfo\n ) external view returns (bool) {\n require(\n bridge.wallets(proposal.walletPubKeyHash).state ==\n Wallets.WalletState.Live,\n \"Wallet is not in Live state\"\n );\n\n require(proposal.depositsKeys.length > 0, \"Sweep below the min size\");\n\n require(\n proposal.depositsKeys.length <= depositSweepMaxSize,\n \"Sweep exceeds the max size\"\n );\n\n require(\n proposal.depositsKeys.length == depositsExtraInfo.length,\n \"Each deposit key must have matching extra data\"\n );\n\n validateSweepTxFee(proposal.sweepTxFee, proposal.depositsKeys.length);\n\n address proposalVault = address(0);\n\n uint256[] memory processedDepositKeys = new uint256[](\n proposal.depositsKeys.length\n );\n\n for (uint256 i = 0; i < proposal.depositsKeys.length; i++) {\n DepositKey memory depositKey = proposal.depositsKeys[i];\n DepositExtraInfo memory depositExtraInfo = depositsExtraInfo[i];\n\n uint256 depositKeyUint = uint256(\n keccak256(\n abi.encodePacked(\n depositKey.fundingTxHash,\n depositKey.fundingOutputIndex\n )\n )\n );\n\n // slither-disable-next-line calls-loop\n Deposit.DepositRequest memory depositRequest = bridge.deposits(\n depositKeyUint\n );\n\n require(depositRequest.revealedAt != 0, \"Deposit not revealed\");\n\n require(\n /* solhint-disable-next-line not-rely-on-time */\n block.timestamp > depositRequest.revealedAt + depositMinAge,\n \"Deposit min age not achieved yet\"\n );\n\n require(depositRequest.sweptAt == 0, \"Deposit already swept\");\n\n validateDepositExtraInfo(\n depositKey,\n depositRequest.depositor,\n depositExtraInfo\n );\n\n uint32 depositRefundableTimestamp = BTCUtils.reverseUint32(\n uint32(depositExtraInfo.refundLocktime)\n );\n require(\n /* solhint-disable-next-line not-rely-on-time */\n block.timestamp <\n depositRefundableTimestamp - depositRefundSafetyMargin,\n \"Deposit refund safety margin is not preserved\"\n );\n\n require(\n depositExtraInfo.walletPubKeyHash == proposal.walletPubKeyHash,\n \"Deposit controlled by different wallet\"\n );\n\n // Make sure all deposits target the same vault by using the\n // vault of the first deposit as a reference.\n if (i == 0) {\n proposalVault = depositRequest.vault;\n }\n require(\n depositRequest.vault == proposalVault,\n \"Deposit targets different vault\"\n );\n\n // Make sure there are no duplicates in the deposits list.\n for (uint256 j = 0; j < i; j++) {\n require(\n processedDepositKeys[j] != depositKeyUint,\n \"Duplicated deposit\"\n );\n }\n\n processedDepositKeys[i] = depositKeyUint;\n }\n\n return true;\n }\n\n /// @notice Validates the sweep tx fee by checking if the part of the fee\n /// incurred by each deposit does not exceed the maximum value\n /// allowed by the Bridge. This function is heavily based on\n /// `DepositSweep.depositSweepTxFeeDistribution` function.\n /// @param sweepTxFee The sweep transaction fee.\n /// @param depositsCount Count of the deposits swept by the sweep transaction.\n /// @dev Requirements:\n /// - The sweep tx fee must be grater than zero,\n /// - The maximum per-deposit sweep tx fee must be lesser than or equal\n /// the maximum fee allowed by the Bridge (`Bridge.depositTxMaxFee`).\n function validateSweepTxFee(uint256 sweepTxFee, uint256 depositsCount)\n internal\n view\n {\n require(sweepTxFee > 0, \"Proposed transaction fee cannot be zero\");\n\n // Compute the indivisible remainder that remains after dividing the\n // sweep transaction fee over all deposits evenly.\n uint256 depositTxFeeRemainder = sweepTxFee % depositsCount;\n // Compute the transaction fee per deposit by dividing the sweep\n // transaction fee (reduced by the remainder) by the number of deposits.\n uint256 depositTxFee = (sweepTxFee - depositTxFeeRemainder) /\n depositsCount;\n\n (, , uint64 depositTxMaxFee, ) = bridge.depositParameters();\n\n // The transaction fee is incurred by each deposit evenly except for the last\n // deposit that has the indivisible remainder additionally incurred.\n // See `DepositSweep.submitDepositSweepProof`.\n // We must make sure the highest value of the deposit transaction fee does\n // not exceed the maximum value limited by the governable parameter.\n require(\n depositTxFee + depositTxFeeRemainder <= depositTxMaxFee,\n \"Proposed transaction fee is too high\"\n );\n }\n\n /// @notice Validates the extra data for the given deposit. This function\n /// is heavily based on `Deposit.revealDeposit` function.\n /// @param depositKey Key of the given deposit.\n /// @param depositor Depositor that revealed the deposit.\n /// @param depositExtraInfo Extra data being subject of the validation.\n /// @dev Requirements:\n /// - The transaction hash computed using `depositExtraInfo.fundingTx`\n /// must match the `depositKey.fundingTxHash`. This requirement\n /// ensures the funding transaction data provided in the extra\n /// data container actually represent the funding transaction of\n /// the given deposit.\n /// - The P2(W)SH script inferred from `depositExtraInfo` is actually\n /// used to lock funds by the `depositKey.fundingOutputIndex` output\n /// of the `depositExtraInfo.fundingTx` transaction. This requirement\n /// ensures the reveal data provided in the extra data container\n /// actually matches the given deposit.\n function validateDepositExtraInfo(\n DepositKey memory depositKey,\n address depositor,\n DepositExtraInfo memory depositExtraInfo\n ) internal view {\n bytes32 depositExtraFundingTxHash = abi\n .encodePacked(\n depositExtraInfo.fundingTx.version,\n depositExtraInfo.fundingTx.inputVector,\n depositExtraInfo.fundingTx.outputVector,\n depositExtraInfo.fundingTx.locktime\n )\n .hash256View();\n\n // Make sure the funding tx provided as part of deposit extra data\n // actually matches the deposit referred by the given deposit key.\n if (depositKey.fundingTxHash != depositExtraFundingTxHash) {\n revert(\"Extra info funding tx hash does not match\");\n }\n\n bytes memory expectedScript = abi.encodePacked(\n hex\"14\", // Byte length of depositor Ethereum address.\n depositor,\n hex\"75\", // OP_DROP\n hex\"08\", // Byte length of blinding factor value.\n depositExtraInfo.blindingFactor,\n hex\"75\", // OP_DROP\n hex\"76\", // OP_DUP\n hex\"a9\", // OP_HASH160\n hex\"14\", // Byte length of a compressed Bitcoin public key hash.\n depositExtraInfo.walletPubKeyHash,\n hex\"87\", // OP_EQUAL\n hex\"63\", // OP_IF\n hex\"ac\", // OP_CHECKSIG\n hex\"67\", // OP_ELSE\n hex\"76\", // OP_DUP\n hex\"a9\", // OP_HASH160\n hex\"14\", // Byte length of a compressed Bitcoin public key hash.\n depositExtraInfo.refundPubKeyHash,\n hex\"88\", // OP_EQUALVERIFY\n hex\"04\", // Byte length of refund locktime value.\n depositExtraInfo.refundLocktime,\n hex\"b1\", // OP_CHECKLOCKTIMEVERIFY\n hex\"75\", // OP_DROP\n hex\"ac\", // OP_CHECKSIG\n hex\"68\" // OP_ENDIF\n );\n\n bytes memory fundingOutput = depositExtraInfo\n .fundingTx\n .outputVector\n .extractOutputAtIndex(depositKey.fundingOutputIndex);\n bytes memory fundingOutputHash = fundingOutput.extractHash();\n\n // Path that checks the deposit extra data validity in case the\n // referred deposit is a P2SH.\n if (\n // slither-disable-next-line calls-loop\n fundingOutputHash.length == 20 &&\n fundingOutputHash.slice20(0) == expectedScript.hash160View()\n ) {\n return;\n }\n\n // Path that checks the deposit extra data validity in case the\n // referred deposit is a P2WSH.\n if (\n fundingOutputHash.length == 32 &&\n fundingOutputHash.toBytes32() == sha256(expectedScript)\n ) {\n return;\n }\n\n revert(\"Extra info funding output script does not match\");\n }\n\n /// @notice Updates parameters related to redemption proposal.\n /// @param _redemptionProposalValidity The new value of `redemptionProposalValidity`.\n /// @param _redemptionRequestMinAge The new value of `redemptionRequestMinAge`.\n /// @param _redemptionRequestTimeoutSafetyMargin The new value of\n /// `redemptionRequestTimeoutSafetyMargin`.\n /// @param _redemptionMaxSize The new value of `redemptionMaxSize`.\n /// @param _redemptionProposalSubmissionGasOffset The new value of\n /// `redemptionProposalSubmissionGasOffset`.\n /// @dev Requirements:\n /// - The caller must be the owner.\n function updateRedemptionProposalParameters(\n uint32 _redemptionProposalValidity,\n uint32 _redemptionRequestMinAge,\n uint32 _redemptionRequestTimeoutSafetyMargin,\n uint16 _redemptionMaxSize,\n uint32 _redemptionProposalSubmissionGasOffset\n ) external onlyOwner {\n redemptionProposalValidity = _redemptionProposalValidity;\n redemptionRequestMinAge = _redemptionRequestMinAge;\n redemptionRequestTimeoutSafetyMargin = _redemptionRequestTimeoutSafetyMargin;\n redemptionMaxSize = _redemptionMaxSize;\n redemptionProposalSubmissionGasOffset = _redemptionProposalSubmissionGasOffset;\n\n emit RedemptionProposalParametersUpdated(\n _redemptionProposalValidity,\n _redemptionRequestMinAge,\n _redemptionRequestTimeoutSafetyMargin,\n _redemptionMaxSize,\n _redemptionProposalSubmissionGasOffset\n );\n }\n\n /// @notice Submits a redemption proposal. Locks the target wallet\n /// for a specific time, equal to the proposal validity period.\n /// This function does not store the proposal in the state but\n /// just emits an event that serves as a guiding light for wallet\n /// off-chain members. Wallet members are supposed to validate\n /// the proposal on their own, before taking any action.\n /// @param proposal The redemption proposal\n /// @dev Requirements:\n /// - The caller is a coordinator,\n /// - The wallet is not time-locked.\n function submitRedemptionProposal(RedemptionProposal calldata proposal)\n public\n onlyCoordinator\n onlyAfterWalletLock(proposal.walletPubKeyHash)\n {\n walletLock[proposal.walletPubKeyHash] = WalletLock(\n /* solhint-disable-next-line not-rely-on-time */\n uint32(block.timestamp) + redemptionProposalValidity,\n WalletAction.Redemption\n );\n\n emit RedemptionProposalSubmitted(proposal, msg.sender);\n }\n\n /// @notice Wraps `submitRedemptionProposal` call and reimburses the\n /// caller's transaction cost.\n /// @dev See `submitRedemptionProposal` function documentation.\n function submitRedemptionProposalWithReimbursement(\n RedemptionProposal calldata proposal\n ) external {\n uint256 gasStart = gasleft();\n\n submitRedemptionProposal(proposal);\n\n reimbursementPool.refund(\n (gasStart - gasleft()) + redemptionProposalSubmissionGasOffset,\n msg.sender\n );\n }\n\n /// @notice View function encapsulating the main rules of a valid redemption\n /// proposal. This function is meant to facilitate the off-chain\n /// validation of the incoming proposals. Thanks to it, most\n /// of the work can be done using a single readonly contract call.\n /// @param proposal The redemption proposal to validate.\n /// @return True if the proposal is valid. Reverts otherwise.\n /// @dev Requirements:\n /// - The target wallet must be in the Live state,\n /// - The number of redemption requests included in the redemption\n /// proposal must be in the range [1, `redemptionMaxSize`],\n /// - The proposed redemption tx fee must be grater than zero,\n /// - The proposed redemption tx fee must be lesser than or equal to\n /// the maximum total fee allowed by the Bridge\n /// (`Bridge.redemptionTxMaxTotalFee`),\n /// - The proposed maximum per-request redemption tx fee share must be\n /// lesser than or equal to the maximum fee share allowed by the\n /// given request (`RedemptionRequest.txMaxFee`),\n /// - Each request must be a pending request registered in the Bridge,\n /// - Each request must be old enough, i.e. at least `redemptionRequestMinAge`\n /// elapsed since their creation time,\n /// - Each request must have the timeout safety margin preserved,\n /// - Each request must be unique.\n function validateRedemptionProposal(RedemptionProposal calldata proposal)\n external\n view\n returns (bool)\n {\n require(\n bridge.wallets(proposal.walletPubKeyHash).state ==\n Wallets.WalletState.Live,\n \"Wallet is not in Live state\"\n );\n\n uint256 requestsCount = proposal.redeemersOutputScripts.length;\n\n require(requestsCount > 0, \"Redemption below the min size\");\n\n require(\n requestsCount <= redemptionMaxSize,\n \"Redemption exceeds the max size\"\n );\n\n (\n ,\n ,\n ,\n uint64 redemptionTxMaxTotalFee,\n uint32 redemptionTimeout,\n ,\n\n ) = bridge.redemptionParameters();\n\n require(\n proposal.redemptionTxFee > 0,\n \"Proposed transaction fee cannot be zero\"\n );\n\n // Make sure the proposed fee does not exceed the total fee limit.\n require(\n proposal.redemptionTxFee <= redemptionTxMaxTotalFee,\n \"Proposed transaction fee is too high\"\n );\n\n // Compute the indivisible remainder that remains after dividing the\n // redemption transaction fee over all requests evenly.\n uint256 redemptionTxFeeRemainder = proposal.redemptionTxFee %\n requestsCount;\n // Compute the transaction fee per request by dividing the redemption\n // transaction fee (reduced by the remainder) by the number of requests.\n uint256 redemptionTxFeePerRequest = (proposal.redemptionTxFee -\n redemptionTxFeeRemainder) / requestsCount;\n\n uint256[] memory processedRedemptionKeys = new uint256[](requestsCount);\n\n for (uint256 i = 0; i < requestsCount; i++) {\n bytes memory script = proposal.redeemersOutputScripts[i];\n\n // As the wallet public key hash is part of the redemption key,\n // we have an implicit guarantee that all requests being part\n // of the proposal target the same wallet.\n uint256 redemptionKey = uint256(\n keccak256(\n abi.encodePacked(\n keccak256(script),\n proposal.walletPubKeyHash\n )\n )\n );\n\n // slither-disable-next-line calls-loop\n Redemption.RedemptionRequest memory redemptionRequest = bridge\n .pendingRedemptions(redemptionKey);\n\n require(\n redemptionRequest.requestedAt != 0,\n \"Not a pending redemption request\"\n );\n\n require(\n /* solhint-disable-next-line not-rely-on-time */\n block.timestamp >\n redemptionRequest.requestedAt + redemptionRequestMinAge,\n \"Redemption request min age not achieved yet\"\n );\n\n // Calculate the timeout the given request times out at.\n uint32 requestTimeout = redemptionRequest.requestedAt +\n redemptionTimeout;\n // Make sure we are far enough from the moment the request times out.\n require(\n /* solhint-disable-next-line not-rely-on-time */\n block.timestamp <\n requestTimeout - redemptionRequestTimeoutSafetyMargin,\n \"Redemption request timeout safety margin is not preserved\"\n );\n\n uint256 feePerRequest = redemptionTxFeePerRequest;\n // The last request incurs the fee remainder.\n if (i == requestsCount - 1) {\n feePerRequest += redemptionTxFeeRemainder;\n }\n // Make sure the redemption transaction fee share incurred by\n // the given request fits in the limit for that request.\n require(\n feePerRequest <= redemptionRequest.txMaxFee,\n \"Proposed transaction per-request fee share is too high\"\n );\n\n // Make sure there are no duplicates in the requests list.\n for (uint256 j = 0; j < i; j++) {\n require(\n processedRedemptionKeys[j] != redemptionKey,\n \"Duplicated request\"\n );\n }\n\n processedRedemptionKeys[i] = redemptionKey;\n }\n\n return true;\n }\n}\n" + }, + "contracts/bridge/Wallets.sol": { + "content": "// SPDX-License-Identifier: GPL-3.0-only\n\n// ██████████████ ▐████▌ ██████████████\n// ██████████████ ▐████▌ ██████████████\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ██████████████ ▐████▌ ██████████████\n// ██████████████ ▐████▌ ██████████████\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n\npragma solidity 0.8.17;\n\nimport {BTCUtils} from \"@keep-network/bitcoin-spv-sol/contracts/BTCUtils.sol\";\nimport {EcdsaDkg} from \"@keep-network/ecdsa/contracts/libraries/EcdsaDkg.sol\";\nimport {Math} from \"@openzeppelin/contracts/utils/math/Math.sol\";\n\nimport \"./BitcoinTx.sol\";\nimport \"./EcdsaLib.sol\";\nimport \"./BridgeState.sol\";\n\n/// @title Wallet library\n/// @notice Library responsible for handling integration between Bridge\n/// contract and ECDSA wallets.\nlibrary Wallets {\n using BTCUtils for bytes;\n\n /// @notice Represents wallet state:\n enum WalletState {\n /// @dev The wallet is unknown to the Bridge.\n Unknown,\n /// @dev The wallet can sweep deposits and accept redemption requests.\n Live,\n /// @dev The wallet was deemed unhealthy and is expected to move their\n /// outstanding funds to another wallet. The wallet can still\n /// fulfill their pending redemption requests although new\n /// redemption requests and new deposit reveals are not accepted.\n MovingFunds,\n /// @dev The wallet moved or redeemed all their funds and is in the\n /// closing period where it is still a subject of fraud challenges\n /// and must defend against them. This state is needed to protect\n /// against deposit frauds on deposits revealed but not swept.\n /// The closing period must be greater that the deposit refund\n /// time plus some time margin.\n Closing,\n /// @dev The wallet finalized the closing period successfully and\n /// can no longer perform any action in the Bridge.\n Closed,\n /// @dev The wallet committed a fraud that was reported, did not move\n /// funds to another wallet before a timeout, or did not sweep\n /// funds moved to if from another wallet before a timeout. The\n /// wallet is blocked and can not perform any actions in the Bridge.\n /// Off-chain coordination with the wallet operators is needed to\n /// recover funds.\n Terminated\n }\n\n /// @notice Holds information about a wallet.\n struct Wallet {\n // Identifier of a ECDSA Wallet registered in the ECDSA Wallet Registry.\n bytes32 ecdsaWalletID;\n // Latest wallet's main UTXO hash computed as\n // keccak256(txHash | txOutputIndex | txOutputValue). The `tx` prefix\n // refers to the transaction which created that main UTXO. The `txHash`\n // is `bytes32` (ordered as in Bitcoin internally), `txOutputIndex`\n // an `uint32`, and `txOutputValue` an `uint64` value.\n bytes32 mainUtxoHash;\n // The total redeemable value of pending redemption requests targeting\n // that wallet.\n uint64 pendingRedemptionsValue;\n // UNIX timestamp the wallet was created at.\n // XXX: Unsigned 32-bit int unix seconds, will break February 7th 2106.\n uint32 createdAt;\n // UNIX timestamp indicating the moment the wallet was requested to\n // move their funds.\n // XXX: Unsigned 32-bit int unix seconds, will break February 7th 2106.\n uint32 movingFundsRequestedAt;\n // UNIX timestamp indicating the moment the wallet's closing period\n // started.\n // XXX: Unsigned 32-bit int unix seconds, will break February 7th 2106.\n uint32 closingStartedAt;\n // Total count of pending moved funds sweep requests targeting this wallet.\n uint32 pendingMovedFundsSweepRequestsCount;\n // Current state of the wallet.\n WalletState state;\n // Moving funds target wallet commitment submitted by the wallet. It\n // is built by applying the keccak256 hash over the list of 20-byte\n // public key hashes of the target wallets.\n bytes32 movingFundsTargetWalletsCommitmentHash;\n // This struct doesn't contain `__gap` property as the structure is stored\n // in a mapping, mappings store values in different slots and they are\n // not contiguous with other values.\n }\n\n event NewWalletRequested();\n\n event NewWalletRegistered(\n bytes32 indexed ecdsaWalletID,\n bytes20 indexed walletPubKeyHash\n );\n\n event WalletMovingFunds(\n bytes32 indexed ecdsaWalletID,\n bytes20 indexed walletPubKeyHash\n );\n\n event WalletClosing(\n bytes32 indexed ecdsaWalletID,\n bytes20 indexed walletPubKeyHash\n );\n\n event WalletClosed(\n bytes32 indexed ecdsaWalletID,\n bytes20 indexed walletPubKeyHash\n );\n\n event WalletTerminated(\n bytes32 indexed ecdsaWalletID,\n bytes20 indexed walletPubKeyHash\n );\n\n /// @notice Requests creation of a new wallet. This function just\n /// forms a request and the creation process is performed\n /// asynchronously. Outcome of that process should be delivered\n /// using `registerNewWallet` function.\n /// @param activeWalletMainUtxo Data of the active wallet's main UTXO, as\n /// currently known on the Ethereum chain.\n /// @dev Requirements:\n /// - `activeWalletMainUtxo` components must point to the recent main\n /// UTXO of the given active wallet, as currently known on the\n /// Ethereum chain. If there is no active wallet at the moment, or\n /// the active wallet has no main UTXO, this parameter can be\n /// empty as it is ignored,\n /// - Wallet creation must not be in progress,\n /// - If the active wallet is set, one of the following\n /// conditions must be true:\n /// - The active wallet BTC balance is above the minimum threshold\n /// and the active wallet is old enough, i.e. the creation period\n /// was elapsed since its creation time,\n /// - The active wallet BTC balance is above the maximum threshold.\n function requestNewWallet(\n BridgeState.Storage storage self,\n BitcoinTx.UTXO calldata activeWalletMainUtxo\n ) external {\n require(\n self.ecdsaWalletRegistry.getWalletCreationState() ==\n EcdsaDkg.State.IDLE,\n \"Wallet creation already in progress\"\n );\n\n bytes20 activeWalletPubKeyHash = self.activeWalletPubKeyHash;\n\n // If the active wallet is set, fetch this wallet's details from\n // storage to perform conditions check. The `registerNewWallet`\n // function guarantees an active wallet is always one of the\n // registered ones.\n if (activeWalletPubKeyHash != bytes20(0)) {\n uint64 activeWalletBtcBalance = getWalletBtcBalance(\n self,\n activeWalletPubKeyHash,\n activeWalletMainUtxo\n );\n uint32 activeWalletCreatedAt = self\n .registeredWallets[activeWalletPubKeyHash]\n .createdAt;\n /* solhint-disable-next-line not-rely-on-time */\n bool activeWalletOldEnough = block.timestamp >=\n activeWalletCreatedAt + self.walletCreationPeriod;\n\n require(\n (activeWalletOldEnough &&\n activeWalletBtcBalance >=\n self.walletCreationMinBtcBalance) ||\n activeWalletBtcBalance >= self.walletCreationMaxBtcBalance,\n \"Wallet creation conditions are not met\"\n );\n }\n\n emit NewWalletRequested();\n\n self.ecdsaWalletRegistry.requestNewWallet();\n }\n\n /// @notice Registers a new wallet. This function should be called\n /// after the wallet creation process initiated using\n /// `requestNewWallet` completes and brings the outcomes.\n /// @param ecdsaWalletID Wallet's unique identifier.\n /// @param publicKeyX Wallet's public key's X coordinate.\n /// @param publicKeyY Wallet's public key's Y coordinate.\n /// @dev Requirements:\n /// - The only caller authorized to call this function is `registry`,\n /// - Given wallet data must not belong to an already registered wallet.\n function registerNewWallet(\n BridgeState.Storage storage self,\n bytes32 ecdsaWalletID,\n bytes32 publicKeyX,\n bytes32 publicKeyY\n ) external {\n require(\n msg.sender == address(self.ecdsaWalletRegistry),\n \"Caller is not the ECDSA Wallet Registry\"\n );\n\n // Compress wallet's public key and calculate Bitcoin's hash160 of it.\n bytes20 walletPubKeyHash = bytes20(\n EcdsaLib.compressPublicKey(publicKeyX, publicKeyY).hash160View()\n );\n\n Wallet storage wallet = self.registeredWallets[walletPubKeyHash];\n require(\n wallet.state == WalletState.Unknown,\n \"ECDSA wallet has been already registered\"\n );\n wallet.ecdsaWalletID = ecdsaWalletID;\n wallet.state = WalletState.Live;\n /* solhint-disable-next-line not-rely-on-time */\n wallet.createdAt = uint32(block.timestamp);\n\n // Set the freshly created wallet as the new active wallet.\n self.activeWalletPubKeyHash = walletPubKeyHash;\n\n self.liveWalletsCount++;\n\n emit NewWalletRegistered(ecdsaWalletID, walletPubKeyHash);\n }\n\n /// @notice Handles a notification about a wallet redemption timeout.\n /// Triggers the wallet moving funds process only if the wallet is\n /// still in the Live state. That means multiple action timeouts can\n /// be reported for the same wallet but only the first report\n /// requests the wallet to move their funds. Executes slashing if\n /// the wallet is in Live or MovingFunds state. Allows to notify\n /// redemption timeout also for a Terminated wallet in case the\n /// redemption was requested before the wallet got terminated.\n /// @param walletPubKeyHash 20-byte public key hash of the wallet.\n /// @param walletMembersIDs Identifiers of the wallet signing group members.\n /// @dev Requirements:\n /// - The wallet must be in the `Live`, `MovingFunds`,\n /// or `Terminated` state.\n function notifyWalletRedemptionTimeout(\n BridgeState.Storage storage self,\n bytes20 walletPubKeyHash,\n uint32[] calldata walletMembersIDs\n ) internal {\n Wallet storage wallet = self.registeredWallets[walletPubKeyHash];\n WalletState walletState = wallet.state;\n\n require(\n walletState == WalletState.Live ||\n walletState == WalletState.MovingFunds ||\n walletState == WalletState.Terminated,\n \"Wallet must be in Live or MovingFunds or Terminated state\"\n );\n\n if (\n walletState == Wallets.WalletState.Live ||\n walletState == Wallets.WalletState.MovingFunds\n ) {\n // Slash the wallet operators and reward the notifier\n self.ecdsaWalletRegistry.seize(\n self.redemptionTimeoutSlashingAmount,\n self.redemptionTimeoutNotifierRewardMultiplier,\n msg.sender,\n wallet.ecdsaWalletID,\n walletMembersIDs\n );\n }\n\n if (walletState == WalletState.Live) {\n moveFunds(self, walletPubKeyHash);\n }\n }\n\n /// @notice Handles a notification about a wallet heartbeat failure and\n /// triggers the wallet moving funds process.\n /// @param publicKeyX Wallet's public key's X coordinate.\n /// @param publicKeyY Wallet's public key's Y coordinate.\n /// @dev Requirements:\n /// - The only caller authorized to call this function is `registry`,\n /// - Wallet must be in Live state.\n function notifyWalletHeartbeatFailed(\n BridgeState.Storage storage self,\n bytes32 publicKeyX,\n bytes32 publicKeyY\n ) external {\n require(\n msg.sender == address(self.ecdsaWalletRegistry),\n \"Caller is not the ECDSA Wallet Registry\"\n );\n\n // Compress wallet's public key and calculate Bitcoin's hash160 of it.\n bytes20 walletPubKeyHash = bytes20(\n EcdsaLib.compressPublicKey(publicKeyX, publicKeyY).hash160View()\n );\n\n require(\n self.registeredWallets[walletPubKeyHash].state == WalletState.Live,\n \"Wallet must be in Live state\"\n );\n\n moveFunds(self, walletPubKeyHash);\n }\n\n /// @notice Notifies that the wallet is either old enough or has too few\n /// satoshis left and qualifies to be closed.\n /// @param walletPubKeyHash 20-byte public key hash of the wallet.\n /// @param walletMainUtxo Data of the wallet's main UTXO, as currently\n /// known on the Ethereum chain.\n /// @dev Requirements:\n /// - Wallet must not be set as the current active wallet,\n /// - Wallet must exceed the wallet maximum age OR the wallet BTC\n /// balance must be lesser than the minimum threshold. If the latter\n /// case is true, the `walletMainUtxo` components must point to the\n /// recent main UTXO of the given wallet, as currently known on the\n /// Ethereum chain. If the wallet has no main UTXO, this parameter\n /// can be empty as it is ignored since the wallet balance is\n /// assumed to be zero,\n /// - Wallet must be in Live state.\n function notifyWalletCloseable(\n BridgeState.Storage storage self,\n bytes20 walletPubKeyHash,\n BitcoinTx.UTXO calldata walletMainUtxo\n ) external {\n require(\n self.activeWalletPubKeyHash != walletPubKeyHash,\n \"Active wallet cannot be considered closeable\"\n );\n\n Wallet storage wallet = self.registeredWallets[walletPubKeyHash];\n require(\n wallet.state == WalletState.Live,\n \"Wallet must be in Live state\"\n );\n\n /* solhint-disable-next-line not-rely-on-time */\n bool walletOldEnough = block.timestamp >=\n wallet.createdAt + self.walletMaxAge;\n\n require(\n walletOldEnough ||\n getWalletBtcBalance(self, walletPubKeyHash, walletMainUtxo) <\n self.walletClosureMinBtcBalance,\n \"Wallet needs to be old enough or have too few satoshis\"\n );\n\n moveFunds(self, walletPubKeyHash);\n }\n\n /// @notice Notifies about the end of the closing period for the given wallet.\n /// Closes the wallet ultimately and notifies the ECDSA registry\n /// about this fact.\n /// @param walletPubKeyHash 20-byte public key hash of the wallet.\n /// @dev Requirements:\n /// - The wallet must be in the Closing state,\n /// - The wallet closing period must have elapsed.\n function notifyWalletClosingPeriodElapsed(\n BridgeState.Storage storage self,\n bytes20 walletPubKeyHash\n ) internal {\n Wallet storage wallet = self.registeredWallets[walletPubKeyHash];\n\n require(\n wallet.state == WalletState.Closing,\n \"Wallet must be in Closing state\"\n );\n\n require(\n /* solhint-disable-next-line not-rely-on-time */\n block.timestamp >\n wallet.closingStartedAt + self.walletClosingPeriod,\n \"Closing period has not elapsed yet\"\n );\n\n finalizeWalletClosing(self, walletPubKeyHash);\n }\n\n /// @notice Notifies that the wallet completed the moving funds process\n /// successfully. Checks if the funds were moved to the expected\n /// target wallets. Closes the source wallet if everything went\n /// good and reverts otherwise.\n /// @param walletPubKeyHash 20-byte public key hash of the wallet.\n /// @param targetWalletsHash 32-byte keccak256 hash over the list of\n /// 20-byte public key hashes of the target wallets actually used\n /// within the moving funds transactions.\n /// @dev Requirements:\n /// - The caller must make sure the moving funds transaction actually\n /// happened on Bitcoin chain and fits the protocol requirements,\n /// - The source wallet must be in the MovingFunds state,\n /// - The target wallets commitment must be submitted by the source\n /// wallet,\n /// - The actual target wallets used in the moving funds transaction\n /// must be exactly the same as the target wallets commitment.\n function notifyWalletFundsMoved(\n BridgeState.Storage storage self,\n bytes20 walletPubKeyHash,\n bytes32 targetWalletsHash\n ) internal {\n Wallet storage wallet = self.registeredWallets[walletPubKeyHash];\n // Check that the wallet is in the MovingFunds state but don't check\n // if the moving funds timeout is exceeded. That should give a\n // possibility to move funds in case when timeout was hit but was\n // not reported yet.\n require(\n wallet.state == WalletState.MovingFunds,\n \"Wallet must be in MovingFunds state\"\n );\n\n bytes32 targetWalletsCommitmentHash = wallet\n .movingFundsTargetWalletsCommitmentHash;\n\n require(\n targetWalletsCommitmentHash != bytes32(0),\n \"Target wallets commitment not submitted yet\"\n );\n\n // Make sure that the target wallets where funds were moved to are\n // exactly the same as the ones the source wallet committed to.\n require(\n targetWalletsCommitmentHash == targetWalletsHash,\n \"Target wallets don't correspond to the commitment\"\n );\n\n // If funds were moved, the wallet has no longer a main UTXO.\n delete wallet.mainUtxoHash;\n\n beginWalletClosing(self, walletPubKeyHash);\n }\n\n /// @notice Called when a MovingFunds wallet has a balance below the dust\n /// threshold. Begins the wallet closing.\n /// @param walletPubKeyHash 20-byte public key hash of the wallet.\n /// @dev Requirements:\n /// - The wallet must be in the MovingFunds state.\n function notifyWalletMovingFundsBelowDust(\n BridgeState.Storage storage self,\n bytes20 walletPubKeyHash\n ) internal {\n WalletState walletState = self\n .registeredWallets[walletPubKeyHash]\n .state;\n\n require(\n walletState == Wallets.WalletState.MovingFunds,\n \"Wallet must be in MovingFunds state\"\n );\n\n beginWalletClosing(self, walletPubKeyHash);\n }\n\n /// @notice Called when the timeout for MovingFunds for the wallet elapsed.\n /// Slashes wallet members and terminates the wallet.\n /// @param walletPubKeyHash 20-byte public key hash of the wallet.\n /// @param walletMembersIDs Identifiers of the wallet signing group members.\n /// @dev Requirements:\n /// - The wallet must be in the MovingFunds state.\n function notifyWalletMovingFundsTimeout(\n BridgeState.Storage storage self,\n bytes20 walletPubKeyHash,\n uint32[] calldata walletMembersIDs\n ) internal {\n Wallets.Wallet storage wallet = self.registeredWallets[\n walletPubKeyHash\n ];\n\n require(\n wallet.state == Wallets.WalletState.MovingFunds,\n \"Wallet must be in MovingFunds state\"\n );\n\n self.ecdsaWalletRegistry.seize(\n self.movingFundsTimeoutSlashingAmount,\n self.movingFundsTimeoutNotifierRewardMultiplier,\n msg.sender,\n wallet.ecdsaWalletID,\n walletMembersIDs\n );\n\n terminateWallet(self, walletPubKeyHash);\n }\n\n /// @notice Called when a wallet which was asked to sweep funds moved from\n /// another wallet did not provide a sweeping proof before a timeout.\n /// Slashes and terminates the wallet who failed to provide a proof.\n /// @param walletPubKeyHash 20-byte public key hash of the wallet which was\n /// supposed to sweep funds.\n /// @param walletMembersIDs Identifiers of the wallet signing group members.\n /// @dev Requirements:\n /// - The wallet must be in the `Live`, `MovingFunds`,\n /// or `Terminated` state.\n function notifyWalletMovedFundsSweepTimeout(\n BridgeState.Storage storage self,\n bytes20 walletPubKeyHash,\n uint32[] calldata walletMembersIDs\n ) internal {\n Wallet storage wallet = self.registeredWallets[walletPubKeyHash];\n WalletState walletState = wallet.state;\n\n require(\n walletState == WalletState.Live ||\n walletState == WalletState.MovingFunds ||\n walletState == WalletState.Terminated,\n \"Wallet must be in Live or MovingFunds or Terminated state\"\n );\n\n if (\n walletState == Wallets.WalletState.Live ||\n walletState == Wallets.WalletState.MovingFunds\n ) {\n self.ecdsaWalletRegistry.seize(\n self.movedFundsSweepTimeoutSlashingAmount,\n self.movedFundsSweepTimeoutNotifierRewardMultiplier,\n msg.sender,\n wallet.ecdsaWalletID,\n walletMembersIDs\n );\n\n terminateWallet(self, walletPubKeyHash);\n }\n }\n\n /// @notice Called when a wallet which was challenged for a fraud did not\n /// defeat the challenge before the timeout. Slashes and terminates\n /// the wallet who failed to defeat the challenge. If the wallet is\n /// already terminated, it does nothing.\n /// @param walletPubKeyHash 20-byte public key hash of the wallet which was\n /// supposed to sweep funds.\n /// @param walletMembersIDs Identifiers of the wallet signing group members.\n /// @param challenger Address of the party which submitted the fraud\n /// challenge.\n /// @dev Requirements:\n /// - The wallet must be in the `Live`, `MovingFunds`, `Closing`\n /// or `Terminated` state.\n function notifyWalletFraudChallengeDefeatTimeout(\n BridgeState.Storage storage self,\n bytes20 walletPubKeyHash,\n uint32[] calldata walletMembersIDs,\n address challenger\n ) internal {\n Wallet storage wallet = self.registeredWallets[walletPubKeyHash];\n WalletState walletState = wallet.state;\n\n if (\n walletState == Wallets.WalletState.Live ||\n walletState == Wallets.WalletState.MovingFunds ||\n walletState == Wallets.WalletState.Closing\n ) {\n self.ecdsaWalletRegistry.seize(\n self.fraudSlashingAmount,\n self.fraudNotifierRewardMultiplier,\n challenger,\n wallet.ecdsaWalletID,\n walletMembersIDs\n );\n\n terminateWallet(self, walletPubKeyHash);\n } else if (walletState == Wallets.WalletState.Terminated) {\n // This is a special case when the wallet was already terminated\n // due to a previous deliberate protocol violation. In that\n // case, this function should be still callable for other fraud\n // challenges timeouts in order to let the challenger unlock its\n // ETH deposit back. However, the wallet termination logic is\n // not called and the challenger is not rewarded.\n } else {\n revert(\n \"Wallet must be in Live or MovingFunds or Closing or Terminated state\"\n );\n }\n }\n\n /// @notice Requests a wallet to move their funds. If the wallet balance\n /// is zero, the wallet closing begins immediately. If the move\n /// funds request refers to the current active wallet, such a wallet\n /// is no longer considered active and the active wallet slot\n /// is unset allowing to trigger a new wallet creation immediately.\n /// @param walletPubKeyHash 20-byte public key hash of the wallet.\n /// @dev Requirements:\n /// - The caller must make sure that the wallet is in the Live state.\n function moveFunds(\n BridgeState.Storage storage self,\n bytes20 walletPubKeyHash\n ) internal {\n Wallet storage wallet = self.registeredWallets[walletPubKeyHash];\n\n if (wallet.mainUtxoHash == bytes32(0)) {\n // If the wallet has no main UTXO, that means its BTC balance\n // is zero and the wallet closing should begin immediately.\n beginWalletClosing(self, walletPubKeyHash);\n } else {\n // Otherwise, initialize the moving funds process.\n wallet.state = WalletState.MovingFunds;\n /* solhint-disable-next-line not-rely-on-time */\n wallet.movingFundsRequestedAt = uint32(block.timestamp);\n\n // slither-disable-next-line reentrancy-events\n emit WalletMovingFunds(wallet.ecdsaWalletID, walletPubKeyHash);\n }\n\n if (self.activeWalletPubKeyHash == walletPubKeyHash) {\n // If the move funds request refers to the current active wallet,\n // unset the active wallet and make the wallet creation process\n // possible in order to get a new healthy active wallet.\n delete self.activeWalletPubKeyHash;\n }\n\n self.liveWalletsCount--;\n }\n\n /// @notice Begins the closing period of the given wallet.\n /// @param walletPubKeyHash 20-byte public key hash of the wallet.\n /// @dev Requirements:\n /// - The caller must make sure that the wallet is in the\n /// MovingFunds state.\n function beginWalletClosing(\n BridgeState.Storage storage self,\n bytes20 walletPubKeyHash\n ) internal {\n Wallet storage wallet = self.registeredWallets[walletPubKeyHash];\n // Initialize the closing period.\n wallet.state = WalletState.Closing;\n /* solhint-disable-next-line not-rely-on-time */\n wallet.closingStartedAt = uint32(block.timestamp);\n\n // slither-disable-next-line reentrancy-events\n emit WalletClosing(wallet.ecdsaWalletID, walletPubKeyHash);\n }\n\n /// @notice Finalizes the closing period of the given wallet and notifies\n /// the ECDSA registry about this fact.\n /// @param walletPubKeyHash 20-byte public key hash of the wallet.\n /// @dev Requirements:\n /// - The caller must make sure that the wallet is in the Closing state.\n function finalizeWalletClosing(\n BridgeState.Storage storage self,\n bytes20 walletPubKeyHash\n ) internal {\n Wallet storage wallet = self.registeredWallets[walletPubKeyHash];\n\n wallet.state = WalletState.Closed;\n\n emit WalletClosed(wallet.ecdsaWalletID, walletPubKeyHash);\n\n self.ecdsaWalletRegistry.closeWallet(wallet.ecdsaWalletID);\n }\n\n /// @notice Terminates the given wallet and notifies the ECDSA registry\n /// about this fact. If the wallet termination refers to the current\n /// active wallet, such a wallet is no longer considered active and\n /// the active wallet slot is unset allowing to trigger a new wallet\n /// creation immediately.\n /// @param walletPubKeyHash 20-byte public key hash of the wallet.\n /// @dev Requirements:\n /// - The caller must make sure that the wallet is in the\n /// Live or MovingFunds or Closing state.\n function terminateWallet(\n BridgeState.Storage storage self,\n bytes20 walletPubKeyHash\n ) internal {\n Wallet storage wallet = self.registeredWallets[walletPubKeyHash];\n\n if (wallet.state == WalletState.Live) {\n self.liveWalletsCount--;\n }\n\n wallet.state = WalletState.Terminated;\n\n // slither-disable-next-line reentrancy-events\n emit WalletTerminated(wallet.ecdsaWalletID, walletPubKeyHash);\n\n if (self.activeWalletPubKeyHash == walletPubKeyHash) {\n // If termination refers to the current active wallet,\n // unset the active wallet and make the wallet creation process\n // possible in order to get a new healthy active wallet.\n delete self.activeWalletPubKeyHash;\n }\n\n self.ecdsaWalletRegistry.closeWallet(wallet.ecdsaWalletID);\n }\n\n /// @notice Gets BTC balance for given the wallet.\n /// @param walletPubKeyHash 20-byte public key hash of the wallet.\n /// @param walletMainUtxo Data of the wallet's main UTXO, as currently\n /// known on the Ethereum chain.\n /// @return walletBtcBalance Current BTC balance for the given wallet.\n /// @dev Requirements:\n /// - `walletMainUtxo` components must point to the recent main UTXO\n /// of the given wallet, as currently known on the Ethereum chain.\n /// If the wallet has no main UTXO, this parameter can be empty as it\n /// is ignored.\n function getWalletBtcBalance(\n BridgeState.Storage storage self,\n bytes20 walletPubKeyHash,\n BitcoinTx.UTXO calldata walletMainUtxo\n ) internal view returns (uint64 walletBtcBalance) {\n bytes32 walletMainUtxoHash = self\n .registeredWallets[walletPubKeyHash]\n .mainUtxoHash;\n\n // If the wallet has a main UTXO hash set, cross-check it with the\n // provided plain-text parameter and get the transaction output value\n // as BTC balance. Otherwise, the BTC balance is just zero.\n if (walletMainUtxoHash != bytes32(0)) {\n require(\n keccak256(\n abi.encodePacked(\n walletMainUtxo.txHash,\n walletMainUtxo.txOutputIndex,\n walletMainUtxo.txOutputValue\n )\n ) == walletMainUtxoHash,\n \"Invalid wallet main UTXO data\"\n );\n\n walletBtcBalance = walletMainUtxo.txOutputValue;\n }\n\n return walletBtcBalance;\n }\n}\n" + }, + "contracts/GovernanceUtils.sol": { + "content": "// SPDX-License-Identifier: GPL-3.0-only\n\npragma solidity 0.8.17;\n\nlibrary GovernanceUtils {\n /// @notice Reverts if the governance delay has not passed since\n /// the change initiated time or if the change has not been\n /// initiated.\n /// @param changeInitiatedTimestamp The timestamp at which the change has\n /// been initiated.\n /// @param delay Governance delay.\n function onlyAfterGovernanceDelay(\n uint256 changeInitiatedTimestamp,\n uint256 delay\n ) internal view {\n require(changeInitiatedTimestamp > 0, \"Change not initiated\");\n require(\n /* solhint-disable-next-line not-rely-on-time */\n block.timestamp - changeInitiatedTimestamp >= delay,\n \"Governance delay has not elapsed\"\n );\n }\n\n /// @notice Gets the time remaining until the governable parameter update\n /// can be committed.\n /// @param changeInitiatedTimestamp Timestamp indicating the beginning of\n /// the change.\n /// @param delay Governance delay.\n /// @return Remaining time in seconds.\n function getRemainingGovernanceDelay(\n uint256 changeInitiatedTimestamp,\n uint256 delay\n ) internal view returns (uint256) {\n require(changeInitiatedTimestamp > 0, \"Change not initiated\");\n /* solhint-disable-next-line not-rely-on-time */\n uint256 elapsed = block.timestamp - changeInitiatedTimestamp;\n if (elapsed >= delay) {\n return 0;\n } else {\n return delay - elapsed;\n }\n }\n}\n" + }, + "contracts/hardhat-dependency-compiler/@keep-network/ecdsa/contracts/WalletRegistry.sol": { + "content": "// SPDX-License-Identifier: UNLICENSED\npragma solidity >0.0.0;\nimport '@keep-network/ecdsa/contracts/WalletRegistry.sol';\n" + }, + "contracts/hardhat-dependency-compiler/@openzeppelin/contracts/proxy/transparent/ProxyAdmin.sol": { + "content": "// SPDX-License-Identifier: UNLICENSED\npragma solidity >0.0.0;\nimport '@openzeppelin/contracts/proxy/transparent/ProxyAdmin.sol';\n" + }, + "contracts/hardhat-dependency-compiler/@openzeppelin/contracts/proxy/transparent/TransparentUpgradeableProxy.sol": { + "content": "// SPDX-License-Identifier: UNLICENSED\npragma solidity >0.0.0;\nimport '@openzeppelin/contracts/proxy/transparent/TransparentUpgradeableProxy.sol';\n" + }, + "contracts/l2/L2TBTC.sol": { + "content": "// SPDX-License-Identifier: GPL-3.0-only\n\n// ██████████████ ▐████▌ ██████████████\n// ██████████████ ▐████▌ ██████████████\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ██████████████ ▐████▌ ██████████████\n// ██████████████ ▐████▌ ██████████████\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n\npragma solidity ^0.8.17;\n\nimport \"@openzeppelin/contracts-upgradeable/token/ERC20/extensions/draft-ERC20PermitUpgradeable.sol\";\nimport \"@openzeppelin/contracts-upgradeable/token/ERC20/extensions/ERC20BurnableUpgradeable.sol\";\nimport \"@openzeppelin/contracts-upgradeable/token/ERC20/IERC20Upgradeable.sol\";\nimport \"@openzeppelin/contracts-upgradeable/token/ERC20/utils/SafeERC20Upgradeable.sol\";\nimport \"@openzeppelin/contracts-upgradeable/token/ERC721/IERC721Upgradeable.sol\";\nimport \"@openzeppelin/contracts-upgradeable/access/OwnableUpgradeable.sol\";\nimport \"@openzeppelin/contracts-upgradeable/security/PausableUpgradeable.sol\";\n\n/// @title L2TBTC\n/// @notice Canonical L2/sidechain token implementation. tBTC token is minted on\n/// L1 and locked there to be moved to L2/sidechain. By deploying\n/// a canonical token on each L2/sidechain, we can ensure the supply of\n/// tBTC remains sacrosanct, while enabling quick, interoperable\n/// cross-chain bridges and localizing ecosystem risk.\n///\n/// This contract is flexible enough to:\n/// - Delegate minting authority to a native bridge on the chain, if\n/// present.\n/// - Delegate minting authority to a short list of ecosystem bridges.\n/// - Have mints and burns paused by any one of n guardians, allowing\n/// avoidance of contagion in case of a chain- or bridge-specific\n/// incident.\n/// - Be governed and upgradeable.\n///\n/// The token is burnable by the token holder and supports EIP2612\n/// permits. Token holder can authorize a transfer of their token with\n/// a signature conforming EIP712 standard instead of an on-chain\n/// transaction from their address. Anyone can submit this signature on\n/// the user's behalf by calling the permit function, paying gas fees,\n/// and possibly performing other actions in the same transaction.\n/// The governance can recover ERC20 and ERC721 tokens sent mistakenly\n/// to L2TBTC token contract.\ncontract L2TBTC is\n ERC20Upgradeable,\n ERC20BurnableUpgradeable,\n ERC20PermitUpgradeable,\n OwnableUpgradeable,\n PausableUpgradeable\n{\n using SafeERC20Upgradeable for IERC20Upgradeable;\n\n /// @notice Indicates if the given address is a minter. Only minters can\n /// mint the token.\n mapping(address => bool) public isMinter;\n\n /// @notice List of all minters.\n address[] public minters;\n\n /// @notice Indicates if the given address is a guardian. Only guardians can\n /// pause token mints and burns.\n mapping(address => bool) public isGuardian;\n\n /// @notice List of all guardians.\n address[] public guardians;\n\n event MinterAdded(address indexed minter);\n event MinterRemoved(address indexed minter);\n\n event GuardianAdded(address indexed guardian);\n event GuardianRemoved(address indexed guardian);\n\n modifier onlyMinter() {\n require(isMinter[msg.sender], \"Caller is not a minter\");\n _;\n }\n\n modifier onlyGuardian() {\n require(isGuardian[msg.sender], \"Caller is not a guardian\");\n _;\n }\n\n /// @notice Initializes the token contract.\n /// @param _name The name of the token.\n /// @param _symbol The symbol of the token, usually a shorter version of the\n /// name.\n function initialize(string memory _name, string memory _symbol)\n external\n initializer\n {\n // OpenZeppelin upgradeable contracts documentation says:\n //\n // \"Use with multiple inheritance requires special care. Initializer\n // functions are not linearized by the compiler like constructors.\n // Because of this, each __{ContractName}_init function embeds the\n // linearized calls to all parent initializers. As a consequence,\n // calling two of these init functions can potentially initialize the\n // same contract twice.\"\n //\n // Note that ERC20 extensions do not linearize calls to ERC20Upgradeable\n // initializer so we call all extension initializers individually. At\n // the same time, ERC20PermitUpgradeable does linearize the call to\n // EIP712Upgradeable so we are not using the unchained initializer\n // versions.\n __ERC20_init(_name, _symbol);\n __ERC20Burnable_init();\n __ERC20Permit_init(_name);\n __Ownable_init();\n __Pausable_init();\n }\n\n /// @notice Adds the address to the minters list.\n /// @dev Requirements:\n /// - The caller must be the contract owner.\n /// - `minter` must not be a minter address already.\n /// @param minter The address to be added as a minter.\n function addMinter(address minter) external onlyOwner {\n require(!isMinter[minter], \"This address is already a minter\");\n isMinter[minter] = true;\n minters.push(minter);\n emit MinterAdded(minter);\n }\n\n /// @notice Removes the address from the minters list.\n /// @dev Requirements:\n /// - The caller must be the contract owner.\n /// - `minter` must be a minter address.\n /// @param minter The address to be removed from the minters list.\n function removeMinter(address minter) external onlyOwner {\n require(isMinter[minter], \"This address is not a minter\");\n delete isMinter[minter];\n\n // We do not expect too many minters so a simple loop is safe.\n for (uint256 i = 0; i < minters.length; i++) {\n if (minters[i] == minter) {\n minters[i] = minters[minters.length - 1];\n // slither-disable-next-line costly-loop\n minters.pop();\n break;\n }\n }\n\n emit MinterRemoved(minter);\n }\n\n /// @notice Adds the address to the guardians list.\n /// @dev Requirements:\n /// - The caller must be the contract owner.\n /// - `guardian` must not be a guardian address already.\n /// @param guardian The address to be added as a guardian.\n function addGuardian(address guardian) external onlyOwner {\n require(!isGuardian[guardian], \"This address is already a guardian\");\n isGuardian[guardian] = true;\n guardians.push(guardian);\n emit GuardianAdded(guardian);\n }\n\n /// @notice Removes the address from the guardians list.\n /// @dev Requirements:\n /// - The caller must be the contract owner.\n /// - `guardian` must be a guardian address.\n /// @param guardian The address to be removed from the guardians list.\n function removeGuardian(address guardian) external onlyOwner {\n require(isGuardian[guardian], \"This address is not a guardian\");\n delete isGuardian[guardian];\n\n // We do not expect too many guardians so a simple loop is safe.\n for (uint256 i = 0; i < guardians.length; i++) {\n if (guardians[i] == guardian) {\n guardians[i] = guardians[guardians.length - 1];\n // slither-disable-next-line costly-loop\n guardians.pop();\n break;\n }\n }\n\n emit GuardianRemoved(guardian);\n }\n\n /// @notice Allows the governance of the token contract to recover any ERC20\n /// sent mistakenly to the token contract address.\n /// @param token The address of the token to be recovered.\n /// @param recipient The token recipient address that will receive recovered\n /// tokens.\n /// @param amount The amount to be recovered.\n function recoverERC20(\n IERC20Upgradeable token,\n address recipient,\n uint256 amount\n ) external onlyOwner {\n token.safeTransfer(recipient, amount);\n }\n\n /// @notice Allows the governance of the token contract to recover any\n /// ERC721 sent mistakenly to the token contract address.\n /// @param token The address of the token to be recovered.\n /// @param recipient The token recipient address that will receive the\n /// recovered token.\n /// @param tokenId The ID of the ERC721 token to be recovered.\n function recoverERC721(\n IERC721Upgradeable token,\n address recipient,\n uint256 tokenId,\n bytes calldata data\n ) external onlyOwner {\n token.safeTransferFrom(address(this), recipient, tokenId, data);\n }\n\n /// @notice Allows one of the guardians to pause mints and burns allowing\n /// avoidance of contagion in case of a chain- or bridge-specific\n /// incident.\n /// @dev Requirements:\n /// - The caller must be a guardian.\n /// - The contract must not be already paused.\n function pause() external onlyGuardian {\n _pause();\n }\n\n /// @notice Allows the governance to unpause mints and burns previously\n /// paused by one of the guardians.\n /// @dev Requirements:\n /// - The caller must be the contract owner.\n /// - The contract must be paused.\n function unpause() external onlyOwner {\n _unpause();\n }\n\n /// @notice Allows one of the minters to mint `amount` tokens and assign\n /// them to `account`, increasing the total supply. Emits\n /// a `Transfer` event with `from` set to the zero address.\n /// @dev Requirements:\n /// - The caller must be a minter.\n /// - `account` must not be the zero address.\n /// @param account The address to receive tokens.\n /// @param amount The amount of token to be minted.\n function mint(address account, uint256 amount)\n external\n whenNotPaused\n onlyMinter\n {\n _mint(account, amount);\n }\n\n /// @notice Destroys `amount` tokens from the caller. Emits a `Transfer`\n /// event with `to` set to the zero address.\n /// @dev Requirements:\n /// - The caller must have at least `amount` tokens.\n /// @param amount The amount of token to be burned.\n function burn(uint256 amount) public override whenNotPaused {\n super.burn(amount);\n }\n\n /// @notice Destroys `amount` tokens from `account`, deducting from the\n /// caller's allowance. Emits a `Transfer` event with `to` set to\n /// the zero address.\n /// @dev Requirements:\n /// - The che caller must have allowance for `accounts`'s tokens of at\n /// least `amount`.\n /// - `account` must not be the zero address.\n /// - `account` must have at least `amount` tokens.\n /// @param account The address owning tokens to be burned.\n /// @param amount The amount of token to be burned.\n function burnFrom(address account, uint256 amount)\n public\n override\n whenNotPaused\n {\n super.burnFrom(account, amount);\n }\n\n /// @notice Allows to fetch a list of all minters.\n function getMinters() external view returns (address[] memory) {\n return minters;\n }\n\n /// @notice Allows to fetch a list of all guardians.\n function getGuardians() external view returns (address[] memory) {\n return guardians;\n }\n}\n" + }, + "contracts/l2/L2WormholeGateway.sol": { + "content": "// SPDX-License-Identifier: GPL-3.0-only\n\n// ██████████████ ▐████▌ ██████████████\n// ██████████████ ▐████▌ ██████████████\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ██████████████ ▐████▌ ██████████████\n// ██████████████ ▐████▌ ██████████████\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n\npragma solidity ^0.8.17;\n\nimport \"@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol\";\nimport \"@openzeppelin/contracts-upgradeable/security/ReentrancyGuardUpgradeable.sol\";\nimport \"@openzeppelin/contracts-upgradeable/token/ERC20/utils/SafeERC20Upgradeable.sol\";\nimport \"@openzeppelin/contracts-upgradeable/token/ERC20/IERC20Upgradeable.sol\";\n\nimport \"./L2TBTC.sol\";\n\n/// @title IWormholeTokenBridge\n/// @notice Wormhole Token Bridge interface. Contains only selected functions\n/// used by L2WormholeGateway.\ninterface IWormholeTokenBridge {\n function completeTransferWithPayload(bytes memory encodedVm)\n external\n returns (bytes memory);\n\n function parseTransferWithPayload(bytes memory encoded)\n external\n pure\n returns (TransferWithPayload memory transfer);\n\n function transferTokens(\n address token,\n uint256 amount,\n uint16 recipientChain,\n bytes32 recipient,\n uint256 arbiterFee,\n uint32 nonce\n ) external payable returns (uint64 sequence);\n\n function transferTokensWithPayload(\n address token,\n uint256 amount,\n uint16 recipientChain,\n bytes32 recipient,\n uint32 nonce,\n bytes memory payload\n ) external payable returns (uint64 sequence);\n\n struct TransferWithPayload {\n uint8 payloadID;\n uint256 amount;\n bytes32 tokenAddress;\n uint16 tokenChain;\n bytes32 to;\n uint16 toChain;\n bytes32 fromAddress;\n bytes payload;\n }\n}\n\n/// @title L2WormholeGateway\n/// @notice Selected cross-ecosystem bridges are given the minting authority for\n/// tBTC token on L2 and sidechains. This contract gives a minting\n/// authority to the Wormhole Bridge.\n///\n/// The process of bridging from L1 to L2 (or sidechain) looks as\n/// follows:\n/// 1. There is a tBTC holder on L1. The holder goes to the Wormhole\n/// Portal and selects the chain they want to bridge to.\n/// 2. The holder submits one transaction to L1 locking their tBTC\n/// tokens in the bridge’s smart contract. After the transaction is\n/// mined, they wait about 15 minutes for the Ethereum block\n/// finality.\n/// 3. The holder submits one transaction to L2 that is minting tokens.\n/// After that transaction is mined, they have their tBTC on L2.\n///\n/// The process of bridging from L2 (or sidechain) to L1 looks as\n/// follows:\n/// 1. There is a tBTC holder on L2. That holder goes to the Wormhole\n/// Portal and selects one of the L2 chains they want to bridge from.\n/// 2. The holder submits one transaction to L2 that is burning the\n/// token. After the transaction is mined, they wait about 15 minutes\n/// for the L2 block finality.\n/// 3. The holder submits one transaction to L1 unlocking their tBTC\n/// tokens from the bridge’s smart contract. After that transaction\n/// is mined, they have their tBTC on L1.\n///\n/// This smart contract is integrated with step 3 of L1->L2 bridging and\n/// step 1 of L2->L1 or L2->L2 bridging. When the user redeems token on\n/// L2, this contract receives the Wormhole tBTC representation and\n/// mints the canonical tBTC in an equal amount. When user sends their\n/// token from L1, this contract burns the canonical tBTC and sends\n/// Wormhole tBTC representation through the bridge in an equal amount.\n/// @dev This contract is supposed to be deployed behind a transparent\n/// upgradeable proxy.\ncontract L2WormholeGateway is\n Initializable,\n OwnableUpgradeable,\n ReentrancyGuardUpgradeable\n{\n using SafeERC20Upgradeable for IERC20Upgradeable;\n\n /// @notice Reference to the Wormhole Token Bridge contract.\n IWormholeTokenBridge public bridge;\n\n /// @notice Wormhole tBTC token representation.\n IERC20Upgradeable public bridgeToken;\n\n /// @notice Canonical tBTC token.\n L2TBTC public tbtc;\n\n /// @notice Maps Wormhole chain ID to the Wormhole tBTC gateway address on\n /// that chain. For example, this chain's ID should be mapped to\n /// this contract's address. If there is no Wormhole tBTC gateway\n /// address on the given chain, there is no entry in this mapping.\n /// The mapping holds addresses in a Wormhole-specific format, where\n /// Ethereum address is left-padded with zeros.\n mapping(uint16 => bytes32) public gateways;\n\n /// @notice Minting limit for this gateway. Useful for early days of testing\n /// the system. The gateway can not mint more canonical tBTC than\n /// this limit.\n uint256 public mintingLimit;\n\n /// @notice The amount of tBTC minted by this contract. tBTC burned by this\n /// contract decreases this amount.\n uint256 public mintedAmount;\n\n event WormholeTbtcReceived(address receiver, uint256 amount);\n\n event WormholeTbtcSent(\n uint256 amount,\n uint16 recipientChain,\n bytes32 gateway,\n bytes32 recipient,\n uint256 arbiterFee,\n uint32 nonce\n );\n\n event WormholeTbtcDeposited(address depositor, uint256 amount);\n\n event GatewayAddressUpdated(uint16 chainId, bytes32 gateway);\n\n event MintingLimitUpdated(uint256 mintingLimit);\n\n function initialize(\n IWormholeTokenBridge _bridge,\n IERC20Upgradeable _bridgeToken,\n L2TBTC _tbtc\n ) external initializer {\n __Ownable_init();\n __ReentrancyGuard_init();\n\n require(\n address(_bridge) != address(0),\n \"Wormhole bridge address must not be 0x0\"\n );\n require(\n address(_bridgeToken) != address(0),\n \"Bridge token address must not be 0x0\"\n );\n require(\n address(_tbtc) != address(0),\n \"L2TBTC token address must not be 0x0\"\n );\n\n bridge = _bridge;\n bridgeToken = _bridgeToken;\n tbtc = _tbtc;\n mintingLimit = type(uint256).max;\n }\n\n /// @notice This function is called when the user sends their token from L2.\n /// The contract burns the canonical tBTC from the user and sends\n /// wormhole tBTC representation over the bridge.\n /// Keep in mind that when multiple bridges receive a minting\n /// authority on the canonical tBTC, this function may not be able\n /// to send all amounts of tBTC through the Wormhole bridge. The\n /// capability of Wormhole Bridge to send tBTC from the chain is\n /// limited to the amount of tBTC bridged through Wormhole to that\n /// chain.\n /// @dev Requirements:\n /// - The sender must have at least `amount` of the canonical tBTC and\n /// it has to be approved for L2WormholeGateway.\n /// - The L2WormholeGateway must have at least `amount` of the wormhole\n /// tBTC.\n /// - The recipient must not be 0x0.\n /// - The amount to transfer must not be 0,\n /// - The amount to transfer must be >= 10^10 (1e18 precision).\n /// Depending if Wormhole tBTC gateway is registered on the target\n /// chain, this function uses transfer or transfer with payload over\n /// the Wormhole bridge.\n /// @param amount The amount of tBTC to be sent.\n /// @param recipientChain The Wormhole recipient chain ID.\n /// @param recipient The address of the recipient in the Wormhole format.\n /// @param arbiterFee The Wormhole arbiter fee. Ignored if sending\n /// tBTC to chain with Wormhole tBTC gateway.\n /// @param nonce The Wormhole nonce used to batch messages together.\n /// @return The Wormhole sequence number.\n function sendTbtc(\n uint256 amount,\n uint16 recipientChain,\n bytes32 recipient,\n uint256 arbiterFee,\n uint32 nonce\n ) external payable nonReentrant returns (uint64) {\n require(recipient != bytes32(0), \"0x0 recipient not allowed\");\n require(amount != 0, \"Amount must not be 0\");\n\n // Normalize the amount to bridge. The dust can not be bridged due to\n // the decimal shift in the Wormhole Bridge contract.\n amount = normalize(amount);\n\n // Check again after dropping the dust.\n require(amount != 0, \"Amount too low to bridge\");\n\n require(\n bridgeToken.balanceOf(address(this)) >= amount,\n \"Not enough wormhole tBTC in the gateway to bridge\"\n );\n\n bytes32 gateway = gateways[recipientChain];\n\n emit WormholeTbtcSent(\n amount,\n recipientChain,\n gateway,\n recipient,\n arbiterFee,\n nonce\n );\n\n mintedAmount -= amount;\n tbtc.burnFrom(msg.sender, amount);\n bridgeToken.safeApprove(address(bridge), amount);\n\n if (gateway == bytes32(0)) {\n // No Wormhole tBTC gateway on the target chain. The token minted\n // by Wormhole should be considered canonical.\n return\n bridge.transferTokens{value: msg.value}(\n address(bridgeToken),\n amount,\n recipientChain,\n recipient,\n arbiterFee,\n nonce\n );\n } else {\n // There is a Wormhole tBTC gateway on the target chain.\n // The gateway needs to mint canonical tBTC for the recipient\n // encoded in the payload.\n return\n bridge.transferTokensWithPayload{value: msg.value}(\n address(bridgeToken),\n amount,\n recipientChain,\n gateway,\n nonce,\n abi.encode(recipient)\n );\n }\n }\n\n /// @notice This function is called when the user redeems their token on L2.\n /// The contract receives Wormhole tBTC representation and mints the\n /// canonical tBTC for the user.\n /// If the tBTC minting limit has been reached by this contract,\n /// instead of minting tBTC the receiver address receives Wormhole\n /// tBTC representation.\n /// @dev Requirements:\n /// - The receiver of Wormhole tBTC should be the L2WormholeGateway\n /// contract.\n /// - The receiver of the canonical tBTC should be abi-encoded in the\n /// payload.\n /// - The receiver of the canonical tBTC must not be the zero address.\n ///\n /// The Wormhole Token Bridge contract has protection against redeeming\n /// the same VAA again. When a Token Bridge VAA is redeemed, its\n /// message body hash is stored in a map. This map is used to check\n /// whether the hash has already been set in this map. For this reason,\n /// this function does not have to be nonReentrant in theory. However,\n /// to make this function non-dependent on Wormhole Bridge implementation,\n /// we are making it nonReentrant anyway.\n /// @param encodedVm A byte array containing a Wormhole VAA signed by the\n /// guardians.\n function receiveTbtc(bytes calldata encodedVm) external nonReentrant {\n // ITokenBridge.completeTransferWithPayload completes a contract-controlled\n // transfer of an ERC20 token. Calling this function is not enough to\n // ensure L2WormholeGateway received Wormhole tBTC representation.\n // Instead of going too deep into the ITokenBridge implementation,\n // asserting who is the receiver of the token, and which token it is,\n // we check the balance before the ITokenBridge call and the balance\n // after ITokenBridge call. This way, we are sure this contract received\n // Wormhole tBTC token in the given amount. This is transparent to\n // all potential upgrades of ITokenBridge implementation and no other\n // validations are needed.\n uint256 balanceBefore = bridgeToken.balanceOf(address(this));\n bytes memory encoded = bridge.completeTransferWithPayload(encodedVm);\n uint256 balanceAfter = bridgeToken.balanceOf(address(this));\n\n uint256 amount = balanceAfter - balanceBefore;\n // Protect against the custody of irrelevant tokens.\n require(amount > 0, \"No tBTC transferred\");\n\n address receiver = fromWormholeAddress(\n bytes32(bridge.parseTransferWithPayload(encoded).payload)\n );\n require(receiver != address(0), \"0x0 receiver not allowed\");\n\n // We send wormhole tBTC OR mint canonical tBTC. We do not want to send\n // dust. Sending wormhole tBTC is an exceptional situation and we want\n // to keep it simple.\n if (mintedAmount + amount > mintingLimit) {\n bridgeToken.safeTransfer(receiver, amount);\n } else {\n // The function is non-reentrant.\n // slither-disable-next-line reentrancy-benign\n mintedAmount += amount;\n tbtc.mint(receiver, amount);\n }\n\n // The function is non-reentrant.\n // slither-disable-next-line reentrancy-events\n emit WormholeTbtcReceived(receiver, amount);\n }\n\n /// @notice Lets the governance to update the tBTC gateway address on the\n /// chain with the given Wormhole ID.\n /// @dev Use toWormholeAddress function to convert between Ethereum and\n /// Wormhole address formats.\n /// @param chainId Wormhole ID of the chain.\n /// @param gateway Address of tBTC gateway on the given chain in a Wormhole\n /// format.\n function updateGatewayAddress(uint16 chainId, bytes32 gateway)\n external\n onlyOwner\n {\n gateways[chainId] = gateway;\n emit GatewayAddressUpdated(chainId, gateway);\n }\n\n /// @notice Lets the governance to update the tBTC minting limit for this\n /// contract.\n /// @param _mintingLimit The new minting limit.\n function updateMintingLimit(uint256 _mintingLimit) external onlyOwner {\n mintingLimit = _mintingLimit;\n emit MintingLimitUpdated(_mintingLimit);\n }\n\n /// @notice Converts Ethereum address into Wormhole format.\n /// @param _address The address to convert.\n function toWormholeAddress(address _address)\n external\n pure\n returns (bytes32)\n {\n return bytes32(uint256(uint160(_address)));\n }\n\n /// @notice Converts Wormhole address into Ethereum format.\n /// @param _address The address to convert.\n function fromWormholeAddress(bytes32 _address)\n public\n pure\n returns (address)\n {\n return address(uint160(uint256(_address)));\n }\n\n /// @dev Eliminates the dust that cannot be bridged with Wormhole\n /// due to the decimal shift in the Wormhole Bridge contract.\n /// See https://github.com/wormhole-foundation/wormhole/blob/96682bdbeb7c87bfa110eade0554b3d8cbf788d2/ethereum/contracts/bridge/Bridge.sol#L276-L288\n function normalize(uint256 amount) internal pure returns (uint256) {\n // slither-disable-next-line divide-before-multiply\n amount /= 10**10;\n amount *= 10**10;\n return amount;\n }\n}\n" + }, + "contracts/maintainer/MaintainerProxy.sol": { + "content": "// SPDX-License-Identifier: GPL-3.0-only\n\n// ██████████████ ▐████▌ ██████████████\n// ██████████████ ▐████▌ ██████████████\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ██████████████ ▐████▌ ██████████████\n// ██████████████ ▐████▌ ██████████████\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n\npragma solidity 0.8.17;\n\nimport \"@openzeppelin/contracts/access/Ownable.sol\";\nimport \"@keep-network/random-beacon/contracts/Reimbursable.sol\";\nimport \"@keep-network/random-beacon/contracts/ReimbursementPool.sol\";\n\nimport \"../bridge/BitcoinTx.sol\";\nimport \"../bridge/Bridge.sol\";\n\n/// @title Maintainer Proxy\n/// @notice Maintainers are the willing off-chain clients approved by the governance.\n/// Maintainers proxy calls to the `Bridge` contract via 'MaintainerProxy'\n/// and are refunded for the spent gas from the `ReimbursementPool`.\n/// There are two types of maintainers: wallet maintainers and SPV\n/// maintainers.\ncontract MaintainerProxy is Ownable, Reimbursable {\n Bridge public bridge;\n\n /// @notice Authorized wallet maintainers that can interact with the set of\n /// functions for wallet maintainers only. Authorization can be\n /// granted and removed by the governance.\n /// @dev 'Key' is the address of the maintainer. 'Value' represents an index+1\n /// in the 'maintainers' array. 1 was added so the maintainer index can\n /// never be 0 which is a reserved index for a non-existent maintainer\n /// in this map.\n mapping(address => uint256) public isWalletMaintainer;\n\n /// @notice This list of wallet maintainers keeps the order of which wallet\n /// maintainer should be submitting a next transaction. It does not\n /// enforce the order but only tracks who should be next in line.\n address[] public walletMaintainers;\n\n /// @notice Authorized SPV maintainers that can interact with the set of\n /// functions for SPV maintainers only. Authorization can be\n /// granted and removed by the governance.\n /// @dev 'Key' is the address of the maintainer. 'Value' represents an index+1\n /// in the 'maintainers' array. 1 was added so the maintainer index can\n /// never be 0 which is a reserved index for a non-existent maintainer\n /// in this map.\n mapping(address => uint256) public isSpvMaintainer;\n\n /// @notice This list of SPV maintainers keeps the order of which SPV\n /// maintainer should be submitting a next transaction. It does not\n /// enforce the order but only tracks who should be next in line.\n address[] public spvMaintainers;\n\n /// @notice Gas that is meant to balance the submission of deposit sweep proof\n /// overall cost. Can be updated by the governance based on the current\n /// market conditions.\n uint256 public submitDepositSweepProofGasOffset;\n\n /// @notice Gas that is meant to balance the submission of redemption proof\n /// overall cost. Can be updated by the governance based on the current\n /// market conditions.\n uint256 public submitRedemptionProofGasOffset;\n\n /// @notice Gas that is meant to balance the reset of moving funds timeout\n /// overall cost. Can be updated by the governance based on the current\n /// market conditions.\n uint256 public resetMovingFundsTimeoutGasOffset;\n\n /// @notice Gas that is meant to balance the submission of moving funds proof\n /// overall cost. Can be updated by the governance based on the current\n /// market conditions.\n uint256 public submitMovingFundsProofGasOffset;\n\n /// @notice Gas that is meant to balance the notification of moving funds below\n /// dust overall cost. Can be updated by the governance based on the\n /// current market conditions.\n uint256 public notifyMovingFundsBelowDustGasOffset;\n\n /// @notice Gas that is meant to balance the submission of moved funds sweep\n /// proof overall cost. Can be updated by the governance based on the\n /// current market conditions.\n uint256 public submitMovedFundsSweepProofGasOffset;\n\n /// @notice Gas that is meant to balance the request of a new wallet overall\n /// cost. Can be updated by the governance based on the current\n /// market conditions.\n uint256 public requestNewWalletGasOffset;\n\n /// @notice Gas that is meant to balance the notification of closeable wallet\n /// overall cost. Can be updated by the governance based on the current\n /// market conditions.\n uint256 public notifyWalletCloseableGasOffset;\n\n /// @notice Gas that is meant to balance the notification of wallet closing\n /// period elapsed overall cost. Can be updated by the governance\n /// based on the current market conditions.\n uint256 public notifyWalletClosingPeriodElapsedGasOffset;\n\n /// @notice Gas that is meant to balance the defeat fraud challenge\n /// overall cost. Can be updated by the governance based on the current\n /// market conditions.\n uint256 public defeatFraudChallengeGasOffset;\n\n /// @notice Gas that is meant to balance the defeat fraud challenge with heartbeat\n /// overall cost. Can be updated by the governance based on the current\n /// market conditions.\n uint256 public defeatFraudChallengeWithHeartbeatGasOffset;\n\n event WalletMaintainerAuthorized(address indexed maintainer);\n\n event WalletMaintainerUnauthorized(address indexed maintainer);\n\n event SpvMaintainerAuthorized(address indexed maintainer);\n\n event SpvMaintainerUnauthorized(address indexed maintainer);\n\n event BridgeUpdated(address newBridge);\n\n event GasOffsetParametersUpdated(\n uint256 submitDepositSweepProofGasOffset,\n uint256 submitRedemptionProofGasOffset,\n uint256 resetMovingFundsTimeoutGasOffset,\n uint256 submitMovingFundsProofGasOffset,\n uint256 notifyMovingFundsBelowDustGasOffset,\n uint256 submitMovedFundsSweepProofGasOffset,\n uint256 requestNewWalletGasOffset,\n uint256 notifyWalletCloseableGasOffset,\n uint256 notifyWalletClosingPeriodElapsedGasOffset,\n uint256 defeatFraudChallengeGasOffset,\n uint256 defeatFraudChallengeWithHeartbeatGasOffset\n );\n\n modifier onlyWalletMaintainer() {\n require(\n isWalletMaintainer[msg.sender] != 0,\n \"Caller is not authorized\"\n );\n _;\n }\n\n modifier onlySpvMaintainer() {\n require(isSpvMaintainer[msg.sender] != 0, \"Caller is not authorized\");\n _;\n }\n\n modifier onlyReimbursableAdmin() override {\n require(owner() == msg.sender, \"Caller is not the owner\");\n _;\n }\n\n constructor(Bridge _bridge, ReimbursementPool _reimbursementPool) {\n bridge = _bridge;\n reimbursementPool = _reimbursementPool;\n submitDepositSweepProofGasOffset = 30000;\n submitRedemptionProofGasOffset = 4000;\n resetMovingFundsTimeoutGasOffset = 1000;\n submitMovingFundsProofGasOffset = 20000;\n notifyMovingFundsBelowDustGasOffset = 3500;\n submitMovedFundsSweepProofGasOffset = 26000;\n requestNewWalletGasOffset = 3500;\n notifyWalletCloseableGasOffset = 4000;\n notifyWalletClosingPeriodElapsedGasOffset = 3000;\n defeatFraudChallengeGasOffset = 10000;\n defeatFraudChallengeWithHeartbeatGasOffset = 5000;\n }\n\n /// @notice Wraps `Bridge.submitDepositSweepProof` call and reimburses the\n /// caller's transaction cost.\n /// @dev See `Bridge.submitDepositSweepProof` function documentation.\n function submitDepositSweepProof(\n BitcoinTx.Info calldata sweepTx,\n BitcoinTx.Proof calldata sweepProof,\n BitcoinTx.UTXO calldata mainUtxo,\n address vault\n ) external onlySpvMaintainer {\n uint256 gasStart = gasleft();\n\n bridge.submitDepositSweepProof(sweepTx, sweepProof, mainUtxo, vault);\n\n reimbursementPool.refund(\n (gasStart - gasleft()) + submitDepositSweepProofGasOffset,\n msg.sender\n );\n }\n\n /// @notice Wraps `Bridge.submitRedemptionProof` call and reimburses the\n /// caller's transaction cost.\n /// @dev See `Bridge.submitRedemptionProof` function documentation.\n function submitRedemptionProof(\n BitcoinTx.Info calldata redemptionTx,\n BitcoinTx.Proof calldata redemptionProof,\n BitcoinTx.UTXO calldata mainUtxo,\n bytes20 walletPubKeyHash\n ) external onlySpvMaintainer {\n uint256 gasStart = gasleft();\n\n bridge.submitRedemptionProof(\n redemptionTx,\n redemptionProof,\n mainUtxo,\n walletPubKeyHash\n );\n\n reimbursementPool.refund(\n (gasStart - gasleft()) + submitRedemptionProofGasOffset,\n msg.sender\n );\n }\n\n /// @notice Wraps `Bridge.resetMovingFundsTimeout` call and reimburses the\n /// caller's transaction cost.\n /// @dev See `Bridge.resetMovingFundsTimeout` function documentation.\n function resetMovingFundsTimeout(bytes20 walletPubKeyHash) external {\n uint256 gasStart = gasleft();\n\n bridge.resetMovingFundsTimeout(walletPubKeyHash);\n\n reimbursementPool.refund(\n (gasStart - gasleft()) + resetMovingFundsTimeoutGasOffset,\n msg.sender\n );\n }\n\n /// @notice Wraps `Bridge.submitMovingFundsProof` call and reimburses the\n /// caller's transaction cost.\n /// @dev See `Bridge.submitMovingFundsProof` function documentation.\n function submitMovingFundsProof(\n BitcoinTx.Info calldata movingFundsTx,\n BitcoinTx.Proof calldata movingFundsProof,\n BitcoinTx.UTXO calldata mainUtxo,\n bytes20 walletPubKeyHash\n ) external onlySpvMaintainer {\n uint256 gasStart = gasleft();\n\n bridge.submitMovingFundsProof(\n movingFundsTx,\n movingFundsProof,\n mainUtxo,\n walletPubKeyHash\n );\n\n reimbursementPool.refund(\n (gasStart - gasleft()) + submitMovingFundsProofGasOffset,\n msg.sender\n );\n }\n\n /// @notice Wraps `Bridge.notifyMovingFundsBelowDust` call and reimburses the\n /// caller's transaction cost.\n /// @dev See `Bridge.notifyMovingFundsBelowDust` function documentation.\n function notifyMovingFundsBelowDust(\n bytes20 walletPubKeyHash,\n BitcoinTx.UTXO calldata mainUtxo\n ) external onlyWalletMaintainer {\n uint256 gasStart = gasleft();\n\n bridge.notifyMovingFundsBelowDust(walletPubKeyHash, mainUtxo);\n\n reimbursementPool.refund(\n (gasStart - gasleft()) + notifyMovingFundsBelowDustGasOffset,\n msg.sender\n );\n }\n\n /// @notice Wraps `Bridge.submitMovedFundsSweepProof` call and reimburses the\n /// caller's transaction cost.\n /// @dev See `Bridge.submitMovedFundsSweepProof` function documentation.\n function submitMovedFundsSweepProof(\n BitcoinTx.Info calldata sweepTx,\n BitcoinTx.Proof calldata sweepProof,\n BitcoinTx.UTXO calldata mainUtxo\n ) external onlySpvMaintainer {\n uint256 gasStart = gasleft();\n\n bridge.submitMovedFundsSweepProof(sweepTx, sweepProof, mainUtxo);\n\n reimbursementPool.refund(\n (gasStart - gasleft()) + submitMovedFundsSweepProofGasOffset,\n msg.sender\n );\n }\n\n /// @notice Wraps `Bridge.requestNewWallet` call and reimburses the\n /// caller's transaction cost.\n /// @dev See `Bridge.requestNewWallet` function documentation.\n function requestNewWallet(BitcoinTx.UTXO calldata activeWalletMainUtxo)\n external\n onlyWalletMaintainer\n {\n uint256 gasStart = gasleft();\n\n bridge.requestNewWallet(activeWalletMainUtxo);\n\n reimbursementPool.refund(\n (gasStart - gasleft()) + requestNewWalletGasOffset,\n msg.sender\n );\n }\n\n /// @notice Wraps `Bridge.notifyWalletCloseable` call and reimburses the\n /// caller's transaction cost.\n /// @dev See `Bridge.notifyWalletCloseable` function documentation.\n function notifyWalletCloseable(\n bytes20 walletPubKeyHash,\n BitcoinTx.UTXO calldata walletMainUtxo\n ) external onlyWalletMaintainer {\n uint256 gasStart = gasleft();\n\n bridge.notifyWalletCloseable(walletPubKeyHash, walletMainUtxo);\n\n reimbursementPool.refund(\n (gasStart - gasleft()) + notifyWalletCloseableGasOffset,\n msg.sender\n );\n }\n\n /// @notice Wraps `Bridge.notifyWalletClosingPeriodElapsed` call and reimburses\n /// the caller's transaction cost.\n /// @dev See `Bridge.notifyWalletClosingPeriodElapsed` function documentation.\n function notifyWalletClosingPeriodElapsed(bytes20 walletPubKeyHash)\n external\n onlyWalletMaintainer\n {\n uint256 gasStart = gasleft();\n\n bridge.notifyWalletClosingPeriodElapsed(walletPubKeyHash);\n\n reimbursementPool.refund(\n (gasStart - gasleft()) + notifyWalletClosingPeriodElapsedGasOffset,\n msg.sender\n );\n }\n\n /// @notice Wraps `Bridge.defeatFraudChallenge` call and reimburses the\n /// caller's transaction cost.\n /// @dev See `Bridge.defeatFraudChallenge` function documentation.\n function defeatFraudChallenge(\n bytes calldata walletPublicKey,\n bytes calldata preimage,\n bool witness\n ) external {\n uint256 gasStart = gasleft();\n\n bridge.defeatFraudChallenge(walletPublicKey, preimage, witness);\n\n reimbursementPool.refund(\n (gasStart - gasleft()) + defeatFraudChallengeGasOffset,\n msg.sender\n );\n }\n\n /// @notice Wraps `Bridge.defeatFraudChallengeWithHeartbeat` call and\n /// reimburses the caller's transaction cost.\n /// @dev See `Bridge.defeatFraudChallengeWithHeartbeat` function documentation.\n function defeatFraudChallengeWithHeartbeat(\n bytes calldata walletPublicKey,\n bytes calldata heartbeatMessage\n ) external {\n uint256 gasStart = gasleft();\n\n bridge.defeatFraudChallengeWithHeartbeat(\n walletPublicKey,\n heartbeatMessage\n );\n\n reimbursementPool.refund(\n (gasStart - gasleft()) + defeatFraudChallengeWithHeartbeatGasOffset,\n msg.sender\n );\n }\n\n /// @notice Authorize a wallet maintainer that can interact with this\n /// reimbursement pool. Can be authorized by the owner only.\n /// @param maintainer Wallet maintainer to authorize.\n function authorizeWalletMaintainer(address maintainer) external onlyOwner {\n walletMaintainers.push(maintainer);\n isWalletMaintainer[maintainer] = walletMaintainers.length;\n\n emit WalletMaintainerAuthorized(maintainer);\n }\n\n /// @notice Authorize an SPV maintainer that can interact with this\n /// reimbursement pool. Can be authorized by the owner only.\n /// @param maintainer SPV maintainer to authorize.\n function authorizeSpvMaintainer(address maintainer) external onlyOwner {\n spvMaintainers.push(maintainer);\n isSpvMaintainer[maintainer] = spvMaintainers.length;\n\n emit SpvMaintainerAuthorized(maintainer);\n }\n\n /// @notice Unauthorize a wallet maintainer that was previously authorized to\n /// interact with the Maintainer Proxy contract. Can be unauthorized\n /// by the owner only.\n /// @dev The last maintainer is swapped with the one to be unauthorized.\n /// The unauthorized maintainer is then removed from the list. An index\n /// of the last maintainer is changed with the removed maintainer.\n /// Ex.\n /// 'walletMaintainers' list: [0x1, 0x2, 0x3, 0x4, 0x5]\n /// 'isWalletMaintainer' map: [0x1 -> 1, 0x2 -> 2, 0x3 -> 3, 0x4 -> 4, 0x5 -> 5]\n /// unauthorize: 0x3\n /// new 'walletMaintainers' list: [0x1, 0x2, 0x5, 0x4]\n /// new 'isWalletMaintainer' map: [0x1 -> 1, 0x2 -> 2, 0x4 -> 4, 0x5 -> 3]\n /// @param maintainerToUnauthorize Maintainer to unauthorize.\n function unauthorizeWalletMaintainer(address maintainerToUnauthorize)\n external\n onlyOwner\n {\n uint256 maintainerIdToUnauthorize = isWalletMaintainer[\n maintainerToUnauthorize\n ];\n\n require(maintainerIdToUnauthorize != 0, \"No maintainer to unauthorize\");\n\n address lastMaintainerAddress = walletMaintainers[\n walletMaintainers.length - 1\n ];\n\n walletMaintainers[\n maintainerIdToUnauthorize - 1\n ] = lastMaintainerAddress;\n walletMaintainers.pop();\n\n isWalletMaintainer[lastMaintainerAddress] = maintainerIdToUnauthorize;\n\n delete isWalletMaintainer[maintainerToUnauthorize];\n\n emit WalletMaintainerUnauthorized(maintainerToUnauthorize);\n }\n\n /// @notice Unauthorize an SPV maintainer that was previously authorized to\n /// interact with the Maintainer Proxy contract. Can be unauthorized\n /// by the owner only.\n /// @dev The last maintainer is swapped with the one to be unauthorized.\n /// The unauthorized maintainer is then removed from the list. An index\n /// of the last maintainer is changed with the removed maintainer.\n /// Ex.\n /// 'spvMaintainers' list: [0x1, 0x2, 0x3, 0x4, 0x5]\n /// 'isSpvMaintainer' map: [0x1 -> 1, 0x2 -> 2, 0x3 -> 3, 0x4 -> 4, 0x5 -> 5]\n /// unauthorize: 0x3\n /// new 'spvMaintainers' list: [0x1, 0x2, 0x5, 0x4]\n /// new 'isSpvMaintainer' map: [0x1 -> 1, 0x2 -> 2, 0x4 -> 4, 0x5 -> 3]\n /// @param maintainerToUnauthorize Maintainer to unauthorize.\n function unauthorizeSpvMaintainer(address maintainerToUnauthorize)\n external\n onlyOwner\n {\n uint256 maintainerIdToUnauthorize = isSpvMaintainer[\n maintainerToUnauthorize\n ];\n\n require(maintainerIdToUnauthorize != 0, \"No maintainer to unauthorize\");\n\n address lastMaintainerAddress = spvMaintainers[\n spvMaintainers.length - 1\n ];\n\n spvMaintainers[maintainerIdToUnauthorize - 1] = lastMaintainerAddress;\n spvMaintainers.pop();\n\n isSpvMaintainer[lastMaintainerAddress] = maintainerIdToUnauthorize;\n\n delete isSpvMaintainer[maintainerToUnauthorize];\n\n emit SpvMaintainerUnauthorized(maintainerToUnauthorize);\n }\n\n /// @notice Allows the Governance to upgrade the Bridge address.\n /// @dev The function does not implement any governance delay and does not\n /// check the status of the Bridge. The Governance implementation needs\n /// to ensure all requirements for the upgrade are satisfied before\n /// executing this function.\n function updateBridge(Bridge _bridge) external onlyOwner {\n bridge = _bridge;\n\n emit BridgeUpdated(address(_bridge));\n }\n\n /// @notice Updates the values of gas offset parameters.\n /// @dev Can be called only by the contract owner. The caller is responsible\n /// for validating parameters.\n /// @param newSubmitDepositSweepProofGasOffset New submit deposit sweep\n /// proof gas offset.\n /// @param newSubmitRedemptionProofGasOffset New submit redemption proof gas\n /// offset.\n /// @param newResetMovingFundsTimeoutGasOffset New reset moving funds\n /// timeout gas offset.\n /// @param newSubmitMovingFundsProofGasOffset New submit moving funds proof\n /// gas offset.\n /// @param newNotifyMovingFundsBelowDustGasOffset New notify moving funds\n /// below dust gas offset.\n /// @param newSubmitMovedFundsSweepProofGasOffset New submit moved funds\n /// sweep proof gas offset.\n /// @param newRequestNewWalletGasOffset New request new wallet gas offset.\n /// @param newNotifyWalletCloseableGasOffset New notify closeable wallet gas\n /// offset.\n /// @param newNotifyWalletClosingPeriodElapsedGasOffset New notify wallet\n /// closing period elapsed gas offset.\n /// @param newDefeatFraudChallengeGasOffset New defeat fraud challenge gas\n /// offset.\n /// @param newDefeatFraudChallengeWithHeartbeatGasOffset New defeat fraud\n /// challenge with heartbeat gas offset.\n function updateGasOffsetParameters(\n uint256 newSubmitDepositSweepProofGasOffset,\n uint256 newSubmitRedemptionProofGasOffset,\n uint256 newResetMovingFundsTimeoutGasOffset,\n uint256 newSubmitMovingFundsProofGasOffset,\n uint256 newNotifyMovingFundsBelowDustGasOffset,\n uint256 newSubmitMovedFundsSweepProofGasOffset,\n uint256 newRequestNewWalletGasOffset,\n uint256 newNotifyWalletCloseableGasOffset,\n uint256 newNotifyWalletClosingPeriodElapsedGasOffset,\n uint256 newDefeatFraudChallengeGasOffset,\n uint256 newDefeatFraudChallengeWithHeartbeatGasOffset\n ) external onlyOwner {\n submitDepositSweepProofGasOffset = newSubmitDepositSweepProofGasOffset;\n submitRedemptionProofGasOffset = newSubmitRedemptionProofGasOffset;\n resetMovingFundsTimeoutGasOffset = newResetMovingFundsTimeoutGasOffset;\n submitMovingFundsProofGasOffset = newSubmitMovingFundsProofGasOffset;\n notifyMovingFundsBelowDustGasOffset = newNotifyMovingFundsBelowDustGasOffset;\n submitMovedFundsSweepProofGasOffset = newSubmitMovedFundsSweepProofGasOffset;\n requestNewWalletGasOffset = newRequestNewWalletGasOffset;\n notifyWalletCloseableGasOffset = newNotifyWalletCloseableGasOffset;\n notifyWalletClosingPeriodElapsedGasOffset = newNotifyWalletClosingPeriodElapsedGasOffset;\n defeatFraudChallengeGasOffset = newDefeatFraudChallengeGasOffset;\n defeatFraudChallengeWithHeartbeatGasOffset = newDefeatFraudChallengeWithHeartbeatGasOffset;\n\n emit GasOffsetParametersUpdated(\n submitDepositSweepProofGasOffset,\n submitRedemptionProofGasOffset,\n resetMovingFundsTimeoutGasOffset,\n submitMovingFundsProofGasOffset,\n notifyMovingFundsBelowDustGasOffset,\n submitMovedFundsSweepProofGasOffset,\n requestNewWalletGasOffset,\n notifyWalletCloseableGasOffset,\n notifyWalletClosingPeriodElapsedGasOffset,\n defeatFraudChallengeGasOffset,\n defeatFraudChallengeWithHeartbeatGasOffset\n );\n }\n\n /// @notice Gets an entire array of wallet maintainer addresses.\n function allWalletMaintainers() external view returns (address[] memory) {\n return walletMaintainers;\n }\n\n /// @notice Gets an entire array of SPV maintainer addresses.\n function allSpvMaintainers() external view returns (address[] memory) {\n return spvMaintainers;\n }\n}\n" + }, + "contracts/relay/LightRelay.sol": { + "content": "// SPDX-License-Identifier: GPL-3.0-only\n\n// ██████████████ ▐████▌ ██████████████\n// ██████████████ ▐████▌ ██████████████\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ██████████████ ▐████▌ ██████████████\n// ██████████████ ▐████▌ ██████████████\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n\npragma solidity 0.8.17;\n\nimport \"@openzeppelin/contracts/access/Ownable.sol\";\n\nimport {BytesLib} from \"@keep-network/bitcoin-spv-sol/contracts/BytesLib.sol\";\nimport {BTCUtils} from \"@keep-network/bitcoin-spv-sol/contracts/BTCUtils.sol\";\nimport {ValidateSPV} from \"@keep-network/bitcoin-spv-sol/contracts/ValidateSPV.sol\";\n\nimport \"../bridge/IRelay.sol\";\n\nstruct Epoch {\n uint32 timestamp;\n // By definition, bitcoin targets have at least 32 leading zero bits.\n // Thus we can only store the bits that aren't guaranteed to be 0.\n uint224 target;\n}\n\ninterface ILightRelay is IRelay {\n event Genesis(uint256 blockHeight);\n event Retarget(uint256 oldDifficulty, uint256 newDifficulty);\n event ProofLengthChanged(uint256 newLength);\n event AuthorizationRequirementChanged(bool newStatus);\n event SubmitterAuthorized(address submitter);\n event SubmitterDeauthorized(address submitter);\n\n function retarget(bytes memory headers) external;\n\n function validateChain(bytes memory headers)\n external\n view\n returns (uint256 startingHeaderTimestamp, uint256 headerCount);\n\n function getBlockDifficulty(uint256 blockNumber)\n external\n view\n returns (uint256);\n\n function getEpochDifficulty(uint256 epochNumber)\n external\n view\n returns (uint256);\n\n function getRelayRange()\n external\n view\n returns (uint256 relayGenesis, uint256 currentEpochEnd);\n}\n\nlibrary RelayUtils {\n using BytesLib for bytes;\n\n /// @notice Extract the timestamp of the header at the given position.\n /// @param headers Byte array containing the header of interest.\n /// @param at The start of the header in the array.\n /// @return The timestamp of the header.\n /// @dev Assumes that the specified position contains a valid header.\n /// Performs no validation whatsoever.\n function extractTimestampAt(bytes memory headers, uint256 at)\n internal\n pure\n returns (uint32)\n {\n return BTCUtils.reverseUint32(uint32(headers.slice4(68 + at)));\n }\n}\n\n/// @dev THE RELAY MUST NOT BE USED BEFORE GENESIS AND AT LEAST ONE RETARGET.\ncontract LightRelay is Ownable, ILightRelay {\n using BytesLib for bytes;\n using BTCUtils for bytes;\n using ValidateSPV for bytes;\n using RelayUtils for bytes;\n\n bool public ready;\n // Whether the relay requires the address submitting a retarget to be\n // authorised in advance by governance.\n bool public authorizationRequired;\n // Number of blocks required for each side of a retarget proof:\n // a retarget must provide `proofLength` blocks before the retarget\n // and `proofLength` blocks after it.\n // Governable\n // Should be set to a fairly high number (e.g. 20-50) in production.\n uint64 public proofLength;\n // The number of the first epoch recorded by the relay.\n // This should equal the height of the block starting the genesis epoch,\n // divided by 2016, but this is not enforced as the relay has no\n // information about block numbers.\n uint64 public genesisEpoch;\n // The number of the latest epoch whose difficulty is proven to the relay.\n // If the genesis epoch's number is set correctly, and retargets along the\n // way have been legitimate, this equals the height of the block starting\n // the most recent epoch, divided by 2016.\n uint64 public currentEpoch;\n\n uint256 internal currentEpochDifficulty;\n uint256 internal prevEpochDifficulty;\n\n // Each epoch from genesis to the current one, keyed by their numbers.\n mapping(uint256 => Epoch) internal epochs;\n\n mapping(address => bool) public isAuthorized;\n\n modifier relayActive() {\n require(ready, \"Relay is not ready for use\");\n _;\n }\n\n /// @notice Establish a starting point for the relay by providing the\n /// target, timestamp and blockheight of the first block of the relay\n /// genesis epoch.\n /// @param genesisHeader The first block header of the genesis epoch.\n /// @param genesisHeight The block number of the first block of the epoch.\n /// @param genesisProofLength The number of blocks required to accept a\n /// proof.\n /// @dev If the relay is used by querying the current and previous epoch\n /// difficulty, at least one retarget needs to be provided after genesis;\n /// otherwise the prevEpochDifficulty will be uninitialised and zero.\n function genesis(\n bytes calldata genesisHeader,\n uint256 genesisHeight,\n uint64 genesisProofLength\n ) external onlyOwner {\n require(!ready, \"Genesis already performed\");\n\n require(genesisHeader.length == 80, \"Invalid genesis header length\");\n\n require(\n genesisHeight % 2016 == 0,\n \"Invalid height of relay genesis block\"\n );\n\n require(genesisProofLength < 2016, \"Proof length excessive\");\n require(genesisProofLength > 0, \"Proof length may not be zero\");\n\n genesisEpoch = uint64(genesisHeight / 2016);\n currentEpoch = genesisEpoch;\n uint256 genesisTarget = genesisHeader.extractTarget();\n uint256 genesisTimestamp = genesisHeader.extractTimestamp();\n epochs[genesisEpoch] = Epoch(\n uint32(genesisTimestamp),\n uint224(genesisTarget)\n );\n proofLength = genesisProofLength;\n currentEpochDifficulty = BTCUtils.calculateDifficulty(genesisTarget);\n ready = true;\n\n emit Genesis(genesisHeight);\n }\n\n /// @notice Set the number of blocks required to accept a header chain.\n /// @param newLength The required number of blocks. Must be less than 2016.\n /// @dev For production, a high number (e.g. 20-50) is recommended.\n /// Small numbers are accepted but should only be used for testing.\n function setProofLength(uint64 newLength) external relayActive onlyOwner {\n require(newLength < 2016, \"Proof length excessive\");\n require(newLength > 0, \"Proof length may not be zero\");\n require(newLength != proofLength, \"Proof length unchanged\");\n proofLength = newLength;\n emit ProofLengthChanged(newLength);\n }\n\n /// @notice Set whether the relay requires retarget submitters to be\n /// pre-authorised by governance.\n /// @param status True if authorisation is to be required, false if not.\n function setAuthorizationStatus(bool status) external onlyOwner {\n authorizationRequired = status;\n emit AuthorizationRequirementChanged(status);\n }\n\n /// @notice Authorise the given address to submit retarget proofs.\n /// @param submitter The address to be authorised.\n function authorize(address submitter) external onlyOwner {\n isAuthorized[submitter] = true;\n emit SubmitterAuthorized(submitter);\n }\n\n /// @notice Rescind the authorisation of the submitter to retarget.\n /// @param submitter The address to be deauthorised.\n function deauthorize(address submitter) external onlyOwner {\n isAuthorized[submitter] = false;\n emit SubmitterDeauthorized(submitter);\n }\n\n /// @notice Add a new epoch to the relay by providing a proof\n /// of the difficulty before and after the retarget.\n /// @param headers A chain of headers including the last X blocks before\n /// the retarget, followed by the first X blocks after the retarget,\n /// where X equals the current proof length.\n /// @dev Checks that the first X blocks are valid in the most recent epoch,\n /// that the difficulty of the new epoch is calculated correctly according\n /// to the block timestamps, and that the next X blocks would be valid in\n /// the new epoch.\n /// We have no information of block heights, so we cannot enforce that\n /// retargets only happen every 2016 blocks; instead, we assume that this\n /// is the case if a valid proof of work is provided.\n /// It is possible to cheat the relay by providing X blocks from earlier in\n /// the most recent epoch, and then mining X new blocks after them.\n /// However, each of these malicious blocks would have to be mined to a\n /// higher difficulty than the legitimate ones.\n /// Alternatively, if the retarget has not been performed yet, one could\n /// first mine X blocks in the old difficulty with timestamps set far in\n /// the future, and then another X blocks at a greatly reduced difficulty.\n /// In either case, cheating the realy requires more work than mining X\n /// legitimate blocks.\n /// Only the most recent epoch is vulnerable to these attacks; once a\n /// retarget has been proven to the relay, the epoch is immutable even if a\n /// contradictory proof were to be presented later.\n function retarget(bytes memory headers) external relayActive {\n if (authorizationRequired) {\n require(isAuthorized[msg.sender], \"Submitter unauthorized\");\n }\n\n require(\n // Require proofLength headers on both sides of the retarget\n headers.length == (proofLength * 2 * 80),\n \"Invalid header length\"\n );\n\n Epoch storage latest = epochs[currentEpoch];\n\n uint256 oldTarget = latest.target;\n\n bytes32 previousHeaderDigest = bytes32(0);\n\n // Validate old chain\n for (uint256 i = 0; i < proofLength; i++) {\n (\n bytes32 currentDigest,\n uint256 currentHeaderTarget\n ) = validateHeader(headers, i * 80, previousHeaderDigest);\n\n require(\n currentHeaderTarget == oldTarget,\n \"Invalid target in pre-retarget headers\"\n );\n\n previousHeaderDigest = currentDigest;\n }\n\n // get timestamp of retarget block\n uint256 epochEndTimestamp = headers.extractTimestampAt(\n (proofLength - 1) * 80\n );\n\n // An attacker could produce blocks with timestamps in the future,\n // in an attempt to reduce the difficulty after the retarget\n // to make mining the second part of the retarget proof easier.\n // In particular, the attacker could reuse all but one block\n // from the legitimate chain, and only mine the last block.\n // To hinder this, require that the epoch end timestamp does not\n // exceed the ethereum timestamp.\n // NOTE: both are unix seconds, so this comparison should be valid.\n require(\n /* solhint-disable-next-line not-rely-on-time */\n epochEndTimestamp < block.timestamp,\n \"Epoch cannot end in the future\"\n );\n\n // Expected target is the full-length target\n uint256 expectedTarget = BTCUtils.retargetAlgorithm(\n oldTarget,\n latest.timestamp,\n epochEndTimestamp\n );\n\n // Mined target is the header-encoded target\n uint256 minedTarget = 0;\n\n uint256 epochStartTimestamp = headers.extractTimestampAt(\n proofLength * 80\n );\n\n // validate new chain\n for (uint256 j = proofLength; j < proofLength * 2; j++) {\n (\n bytes32 _currentDigest,\n uint256 _currentHeaderTarget\n ) = validateHeader(headers, j * 80, previousHeaderDigest);\n\n if (minedTarget == 0) {\n // The new target has not been set, so check its correctness\n minedTarget = _currentHeaderTarget;\n require(\n // Although the target is a 256-bit number, there are only 32 bits of\n // space in the Bitcoin header. Because of that, the version stored in\n // the header is a less-precise representation of the actual target\n // using base-256 version of scientific notation.\n //\n // The 256-bit unsigned integer returned from BTCUtils.retargetAlgorithm\n // is the precise target value.\n // The 256-bit unsigned integer returned from validateHeader is the less\n // precise target value because it was read from 32 bits of space of\n // Bitcoin block header.\n //\n // We can't compare the precise and less precise representations together\n // so we first mask them to obtain the less precise version:\n // (full & truncated) == truncated\n _currentHeaderTarget ==\n (expectedTarget & _currentHeaderTarget),\n \"Invalid target in new epoch\"\n );\n } else {\n // The new target has been set, so remaining targets should match.\n require(\n _currentHeaderTarget == minedTarget,\n \"Unexpected target change after retarget\"\n );\n }\n\n previousHeaderDigest = _currentDigest;\n }\n\n currentEpoch = currentEpoch + 1;\n\n epochs[currentEpoch] = Epoch(\n uint32(epochStartTimestamp),\n uint224(minedTarget)\n );\n\n uint256 oldDifficulty = currentEpochDifficulty;\n uint256 newDifficulty = BTCUtils.calculateDifficulty(minedTarget);\n\n prevEpochDifficulty = oldDifficulty;\n currentEpochDifficulty = newDifficulty;\n\n emit Retarget(oldDifficulty, newDifficulty);\n }\n\n /// @notice Check whether a given chain of headers should be accepted as\n /// valid within the rules of the relay.\n /// If the validation fails, this function throws an exception.\n /// @param headers A chain of 2 to 2015 bitcoin headers.\n /// @return startingHeaderTimestamp The timestamp of the first header.\n /// @return headerCount The number of headers.\n /// @dev A chain of headers is accepted as valid if:\n /// - Its length is between 2 and 2015 headers.\n /// - Headers in the chain are sequential and refer to previous digests.\n /// - Each header is mined with the correct amount of work.\n /// - The difficulty in each header matches an epoch of the relay,\n /// as determined by the headers' timestamps. The headers must be between\n /// the genesis epoch and the latest proven epoch (inclusive).\n /// If the chain contains a retarget, it is accepted if the retarget has\n /// already been proven to the relay.\n /// If the chain contains blocks of an epoch that has not been proven to\n /// the relay (after a retarget within the header chain, or when the entire\n /// chain falls within an epoch that has not been proven yet), it will be\n /// rejected.\n /// One exception to this is when two subsequent epochs have exactly the\n /// same difficulty; headers from the latter epoch will be accepted if the\n /// previous epoch has been proven to the relay.\n /// This is because it is not possible to distinguish such headers from\n /// headers of the previous epoch.\n ///\n /// If the difficulty increases significantly between relay genesis and the\n /// present, creating fraudulent proofs for earlier epochs becomes easier.\n /// Users of the relay should check the timestamps of valid headers and\n /// only accept appropriately recent ones.\n function validateChain(bytes memory headers)\n external\n view\n returns (uint256 startingHeaderTimestamp, uint256 headerCount)\n {\n require(headers.length % 80 == 0, \"Invalid header length\");\n\n headerCount = headers.length / 80;\n\n require(\n headerCount > 1 && headerCount < 2016,\n \"Invalid number of headers\"\n );\n\n startingHeaderTimestamp = headers.extractTimestamp();\n\n // Short-circuit the first header's validation.\n // We validate the header here to get the target which is needed to\n // precisely identify the epoch.\n (\n bytes32 previousHeaderDigest,\n uint256 currentHeaderTarget\n ) = validateHeader(headers, 0, bytes32(0));\n\n Epoch memory nullEpoch = Epoch(0, 0);\n\n uint256 startingEpochNumber = currentEpoch;\n Epoch memory startingEpoch = epochs[startingEpochNumber];\n Epoch memory nextEpoch = nullEpoch;\n\n // Find the correct epoch for the given chain\n // Fastest with recent epochs, but able to handle anything after genesis\n //\n // The rules for bitcoin timestamps are:\n // - must be greater than the median of the last 11 blocks' timestamps\n // - must be less than the network-adjusted time +2 hours\n //\n // Because of this, the timestamp of a header may be smaller than the\n // starting time, or greater than the ending time of its epoch.\n // However, a valid timestamp is guaranteed to fall within the window\n // formed by the epochs immediately before and after its timestamp.\n // We can identify cases like these by comparing the targets.\n while (startingHeaderTimestamp < startingEpoch.timestamp) {\n startingEpochNumber -= 1;\n nextEpoch = startingEpoch;\n startingEpoch = epochs[startingEpochNumber];\n }\n\n // We have identified the centre of the window,\n // by reaching the most recent epoch whose starting timestamp\n // or reached before the genesis where epoch slots are empty.\n // Therefore check that the timestamp is nonzero.\n require(\n startingEpoch.timestamp > 0,\n \"Cannot validate chains before relay genesis\"\n );\n\n // The targets don't match. This could be because the block is invalid,\n // or it could be because of timestamp inaccuracy.\n // To cover the latter case, check adjacent epochs.\n if (currentHeaderTarget != startingEpoch.target) {\n // The target matches the next epoch.\n // This means we are right at the beginning of the next epoch,\n // and retargets during the chain should not be possible.\n if (currentHeaderTarget == nextEpoch.target) {\n startingEpoch = nextEpoch;\n nextEpoch = nullEpoch;\n }\n // The target doesn't match the next epoch.\n // Therefore the only valid epoch is the previous one.\n // Because the timestamp can't be more than 2 hours into the future\n // we must be right near the end of the epoch,\n // so a retarget is possible.\n else {\n startingEpochNumber -= 1;\n nextEpoch = startingEpoch;\n startingEpoch = epochs[startingEpochNumber];\n\n // We have failed to find a match,\n // therefore the target has to be invalid.\n require(\n currentHeaderTarget == startingEpoch.target,\n \"Invalid target in header chain\"\n );\n }\n }\n\n // We've found the correct epoch for the first header.\n // Validate the rest.\n for (uint256 i = 1; i < headerCount; i++) {\n bytes32 currentDigest;\n (currentDigest, currentHeaderTarget) = validateHeader(\n headers,\n i * 80,\n previousHeaderDigest\n );\n\n // If the header's target does not match the expected target,\n // check if a retarget is possible.\n //\n // If next epoch timestamp exists, a valid retarget is possible\n // (if next epoch timestamp doesn't exist, either a retarget has\n // already happened in this chain, the relay needs a retarget\n // before this chain can be validated, or a retarget is not allowed\n // because we know the headers are within a timestamp irregularity\n // of the previous retarget).\n //\n // In this case the target must match the next epoch's target,\n // and the header's timestamp must match the epoch's start.\n if (currentHeaderTarget != startingEpoch.target) {\n uint256 currentHeaderTimestamp = headers.extractTimestampAt(\n i * 80\n );\n\n require(\n nextEpoch.timestamp != 0 &&\n currentHeaderTarget == nextEpoch.target &&\n currentHeaderTimestamp == nextEpoch.timestamp,\n \"Invalid target in header chain\"\n );\n\n startingEpoch = nextEpoch;\n nextEpoch = nullEpoch;\n }\n\n previousHeaderDigest = currentDigest;\n }\n\n return (startingHeaderTimestamp, headerCount);\n }\n\n /// @notice Get the difficulty of the specified block.\n /// @param blockNumber The number of the block. Must fall within the relay\n /// range (at or after the relay genesis, and at or before the end of the\n /// most recent epoch proven to the relay).\n /// @return The difficulty of the epoch.\n function getBlockDifficulty(uint256 blockNumber)\n external\n view\n returns (uint256)\n {\n return getEpochDifficulty(blockNumber / 2016);\n }\n\n /// @notice Get the range of blocks the relay can accept proofs for.\n /// @dev Assumes that the genesis has been set correctly.\n /// Additionally, if the next epoch after the current one has the exact\n /// same difficulty, headers for it can be validated as well.\n /// This function should be used for informative purposes,\n /// e.g. to determine whether a retarget must be provided before submitting\n /// a header chain for validation.\n /// @return relayGenesis The height of the earliest block that can be\n /// included in header chains for the relay to validate.\n /// @return currentEpochEnd The height of the last block that can be\n /// included in header chains for the relay to validate.\n function getRelayRange()\n external\n view\n returns (uint256 relayGenesis, uint256 currentEpochEnd)\n {\n relayGenesis = genesisEpoch * 2016;\n currentEpochEnd = (currentEpoch * 2016) + 2015;\n }\n\n /// @notice Returns the difficulty of the current epoch.\n /// @dev returns 0 if the relay is not ready.\n /// @return The difficulty of the current epoch.\n function getCurrentEpochDifficulty()\n external\n view\n virtual\n returns (uint256)\n {\n return currentEpochDifficulty;\n }\n\n /// @notice Returns the difficulty of the previous epoch.\n /// @dev Returns 0 if the relay is not ready or has not had a retarget.\n /// @return The difficulty of the previous epoch.\n function getPrevEpochDifficulty() external view virtual returns (uint256) {\n return prevEpochDifficulty;\n }\n\n function getCurrentAndPrevEpochDifficulty()\n external\n view\n returns (uint256 current, uint256 previous)\n {\n return (currentEpochDifficulty, prevEpochDifficulty);\n }\n\n /// @notice Get the difficulty of the specified epoch.\n /// @param epochNumber The number of the epoch (the height of the first\n /// block of the epoch, divided by 2016). Must fall within the relay range.\n /// @return The difficulty of the epoch.\n function getEpochDifficulty(uint256 epochNumber)\n public\n view\n returns (uint256)\n {\n require(epochNumber >= genesisEpoch, \"Epoch is before relay genesis\");\n require(\n epochNumber <= currentEpoch,\n \"Epoch is not proven to the relay yet\"\n );\n return BTCUtils.calculateDifficulty(epochs[epochNumber].target);\n }\n\n /// @notice Check that the specified header forms a correct chain with the\n /// digest of the previous header (if provided), and has sufficient work.\n /// @param headers The byte array containing the header of interest.\n /// @param start The start of the header in the array.\n /// @param prevDigest The digest of the previous header\n /// (optional; providing zeros for the digest skips the check).\n /// @return digest The digest of the current header.\n /// @return target The PoW target of the header.\n /// @dev Throws an exception if the header's chain or PoW are invalid.\n /// Performs no other validation.\n function validateHeader(\n bytes memory headers,\n uint256 start,\n bytes32 prevDigest\n ) internal view returns (bytes32 digest, uint256 target) {\n // If previous block digest has been provided, require that it matches\n if (prevDigest != bytes32(0)) {\n require(\n headers.validateHeaderPrevHash(start, prevDigest),\n \"Invalid chain\"\n );\n }\n\n // Require that the header has sufficient work for its stated target\n target = headers.extractTargetAt(start);\n digest = headers.hash256Slice(start, 80);\n require(ValidateSPV.validateHeaderWork(digest, target), \"Invalid work\");\n\n return (digest, target);\n }\n}\n" + }, + "contracts/relay/LightRelayMaintainerProxy.sol": { + "content": "// SPDX-License-Identifier: GPL-3.0-only\n\n// ██████████████ ▐████▌ ██████████████\n// ██████████████ ▐████▌ ██████████████\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ██████████████ ▐████▌ ██████████████\n// ██████████████ ▐████▌ ██████████████\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n\npragma solidity 0.8.17;\n\nimport \"@openzeppelin/contracts/access/Ownable.sol\";\nimport \"@keep-network/random-beacon/contracts/Reimbursable.sol\";\nimport \"@keep-network/random-beacon/contracts/ReimbursementPool.sol\";\n\nimport \"./LightRelay.sol\";\n\n/// @title LightRelayMaintainerProxy\n/// @notice The proxy contract that allows the relay maintainers to be refunded\n/// for the spent gas from the `ReimbursementPool`. When proving the\n/// next Bitcoin difficulty epoch, the maintainer calls the\n/// `LightRelayMaintainerProxy` which in turn calls the actual `LightRelay`\n/// contract.\ncontract LightRelayMaintainerProxy is Ownable, Reimbursable {\n ILightRelay public lightRelay;\n\n /// @notice Stores the addresses that can maintain the relay. Those\n /// addresses are attested by the DAO.\n /// @dev The goal is to prevent a griefing attack by frontrunning relay\n /// maintainer which is responsible for retargetting the relay in the\n /// given round. The maintainer's transaction would revert with no gas\n /// refund. Having the ability to restrict maintainer addresses is also\n /// important in case the underlying relay contract has authorization\n /// requirements for callers.\n mapping(address => bool) public isAuthorized;\n\n /// @notice Gas that is meant to balance the retarget overall cost. Can be\n // updated by the governance based on the current market conditions.\n uint256 public retargetGasOffset;\n\n event LightRelayUpdated(address newRelay);\n\n event MaintainerAuthorized(address indexed maintainer);\n\n event MaintainerDeauthorized(address indexed maintainer);\n\n event RetargetGasOffsetUpdated(uint256 retargetGasOffset);\n\n modifier onlyRelayMaintainer() {\n require(isAuthorized[msg.sender], \"Caller is not authorized\");\n _;\n }\n\n modifier onlyReimbursableAdmin() override {\n require(owner() == msg.sender, \"Caller is not the owner\");\n _;\n }\n\n constructor(ILightRelay _lightRelay, ReimbursementPool _reimbursementPool) {\n require(\n address(_lightRelay) != address(0),\n \"Light relay must not be zero address\"\n );\n require(\n address(_reimbursementPool) != address(0),\n \"Reimbursement pool must not be zero address\"\n );\n\n lightRelay = _lightRelay;\n reimbursementPool = _reimbursementPool;\n\n retargetGasOffset = 54000;\n }\n\n /// @notice Allows the governance to upgrade the `LightRelay` address.\n /// @dev The function does not implement any governance delay and does not\n /// check the status of the `LightRelay`. The Governance implementation\n /// needs to ensure all requirements for the upgrade are satisfied\n /// before executing this function.\n function updateLightRelay(ILightRelay _lightRelay) external onlyOwner {\n require(\n address(_lightRelay) != address(0),\n \"New light relay must not be zero address\"\n );\n\n lightRelay = _lightRelay;\n emit LightRelayUpdated(address(_lightRelay));\n }\n\n /// @notice Authorizes the given address as a maintainer. Can only be called\n /// by the owner and the address of the maintainer must not be\n /// already authorized.\n /// @dev The function does not implement any governance delay.\n /// @param maintainer The address of the maintainer to be authorized.\n function authorize(address maintainer) external onlyOwner {\n require(!isAuthorized[maintainer], \"Maintainer is already authorized\");\n\n isAuthorized[maintainer] = true;\n emit MaintainerAuthorized(maintainer);\n }\n\n /// @notice Deauthorizes the given address as a maintainer. Can only be\n /// called by the owner and the address of the maintainer must be\n /// authorized.\n /// @dev The function does not implement any governance delay.\n /// @param maintainer The address of the maintainer to be deauthorized.\n function deauthorize(address maintainer) external onlyOwner {\n require(isAuthorized[maintainer], \"Maintainer is not authorized\");\n\n isAuthorized[maintainer] = false;\n emit MaintainerDeauthorized(maintainer);\n }\n\n /// @notice Updates the values of retarget gas offset.\n /// @dev Can be called only by the contract owner. The caller is responsible\n /// for validating the parameter. The function does not implement any\n /// governance delay.\n /// @param newRetargetGasOffset New retarget gas offset.\n function updateRetargetGasOffset(uint256 newRetargetGasOffset)\n external\n onlyOwner\n {\n retargetGasOffset = newRetargetGasOffset;\n emit RetargetGasOffsetUpdated(retargetGasOffset);\n }\n\n /// @notice Wraps `LightRelay.retarget` call and reimburses the caller's\n /// transaction cost. Can only be called by an authorized relay\n /// maintainer.\n /// @dev See `LightRelay.retarget` function documentation.\n function retarget(bytes memory headers) external onlyRelayMaintainer {\n uint256 gasStart = gasleft();\n\n lightRelay.retarget(headers);\n\n reimbursementPool.refund(\n (gasStart - gasleft()) + retargetGasOffset,\n msg.sender\n );\n }\n}\n" + }, + "contracts/test/BankStub.sol": { + "content": "// SPDX-License-Identifier: GPL-3.0-only\n\npragma solidity 0.8.17;\n\nimport \"../bank/Bank.sol\";\n\ncontract BankStub is Bank {\n function setBalance(address addr, uint256 amount) external {\n balanceOf[addr] = amount;\n }\n}\n" + }, + "contracts/test/BridgeStub.sol": { + "content": "// SPDX-License-Identifier: GPL-3.0-only\n\npragma solidity 0.8.17;\n\nimport \"../bridge/BitcoinTx.sol\";\nimport \"../bridge/Bridge.sol\";\nimport \"../bridge/MovingFunds.sol\";\nimport \"../bridge/Wallets.sol\";\n\ncontract BridgeStub is Bridge {\n function setSweptDeposits(BitcoinTx.UTXO[] calldata utxos) external {\n for (uint256 i = 0; i < utxos.length; i++) {\n uint256 utxoKey = uint256(\n keccak256(\n abi.encodePacked(utxos[i].txHash, utxos[i].txOutputIndex)\n )\n );\n self.deposits[utxoKey].sweptAt = 1641650400;\n }\n }\n\n function setSpentMainUtxos(BitcoinTx.UTXO[] calldata utxos) external {\n for (uint256 i = 0; i < utxos.length; i++) {\n uint256 utxoKey = uint256(\n keccak256(\n abi.encodePacked(utxos[i].txHash, utxos[i].txOutputIndex)\n )\n );\n self.spentMainUTXOs[utxoKey] = true;\n }\n }\n\n function setProcessedMovedFundsSweepRequests(\n BitcoinTx.UTXO[] calldata utxos\n ) external {\n for (uint256 i = 0; i < utxos.length; i++) {\n uint256 utxoKey = uint256(\n keccak256(\n abi.encodePacked(utxos[i].txHash, utxos[i].txOutputIndex)\n )\n );\n self.movedFundsSweepRequests[utxoKey].state = MovingFunds\n .MovedFundsSweepRequestState\n .Processed;\n }\n }\n\n function setActiveWallet(bytes20 activeWalletPubKeyHash) external {\n self.activeWalletPubKeyHash = activeWalletPubKeyHash;\n }\n\n function setWalletMainUtxo(\n bytes20 walletPubKeyHash,\n BitcoinTx.UTXO calldata utxo\n ) external {\n self.registeredWallets[walletPubKeyHash].mainUtxoHash = keccak256(\n abi.encodePacked(\n utxo.txHash,\n utxo.txOutputIndex,\n utxo.txOutputValue\n )\n );\n }\n\n function setWallet(bytes20 walletPubKeyHash, Wallets.Wallet calldata wallet)\n external\n {\n self.registeredWallets[walletPubKeyHash] = wallet;\n\n if (wallet.state == Wallets.WalletState.Live) {\n self.liveWalletsCount++;\n }\n }\n\n function setDepositDustThreshold(uint64 _depositDustThreshold) external {\n self.depositDustThreshold = _depositDustThreshold;\n }\n\n function setDepositTxMaxFee(uint64 _depositTxMaxFee) external {\n self.depositTxMaxFee = _depositTxMaxFee;\n }\n\n function setRedemptionDustThreshold(uint64 _redemptionDustThreshold)\n external\n {\n self.redemptionDustThreshold = _redemptionDustThreshold;\n }\n\n function setRedemptionTreasuryFeeDivisor(\n uint64 _redemptionTreasuryFeeDivisor\n ) external {\n self.redemptionTreasuryFeeDivisor = _redemptionTreasuryFeeDivisor;\n }\n\n function setPendingMovedFundsSweepRequest(\n bytes20 walletPubKeyHash,\n BitcoinTx.UTXO calldata utxo\n ) external {\n uint256 requestKey = uint256(\n keccak256(abi.encodePacked(utxo.txHash, utxo.txOutputIndex))\n );\n\n self.movedFundsSweepRequests[requestKey] = MovingFunds\n .MovedFundsSweepRequest(\n walletPubKeyHash,\n utxo.txOutputValue,\n /* solhint-disable-next-line not-rely-on-time */\n uint32(block.timestamp),\n MovingFunds.MovedFundsSweepRequestState.Pending\n );\n\n self\n .registeredWallets[walletPubKeyHash]\n .pendingMovedFundsSweepRequestsCount++;\n }\n\n function processPendingMovedFundsSweepRequest(\n bytes20 walletPubKeyHash,\n BitcoinTx.UTXO calldata utxo\n ) external {\n uint256 requestKey = uint256(\n keccak256(abi.encodePacked(utxo.txHash, utxo.txOutputIndex))\n );\n\n MovingFunds.MovedFundsSweepRequest storage request = self\n .movedFundsSweepRequests[requestKey];\n\n require(\n request.state == MovingFunds.MovedFundsSweepRequestState.Pending,\n \"Stub sweep request must be in Pending state\"\n );\n\n request.state = MovingFunds.MovedFundsSweepRequestState.Processed;\n\n self\n .registeredWallets[walletPubKeyHash]\n .pendingMovedFundsSweepRequestsCount--;\n }\n\n function timeoutPendingMovedFundsSweepRequest(\n bytes20 walletPubKeyHash,\n BitcoinTx.UTXO calldata utxo\n ) external {\n uint256 requestKey = uint256(\n keccak256(abi.encodePacked(utxo.txHash, utxo.txOutputIndex))\n );\n\n MovingFunds.MovedFundsSweepRequest storage request = self\n .movedFundsSweepRequests[requestKey];\n\n require(\n request.state == MovingFunds.MovedFundsSweepRequestState.Pending,\n \"Stub sweep request must be in Pending state\"\n );\n\n request.state = MovingFunds.MovedFundsSweepRequestState.TimedOut;\n\n self\n .registeredWallets[walletPubKeyHash]\n .pendingMovedFundsSweepRequestsCount--;\n }\n\n function setMovedFundsSweepTxMaxTotalFee(\n uint64 _movedFundsSweepTxMaxTotalFee\n ) external {\n self.movedFundsSweepTxMaxTotalFee = _movedFundsSweepTxMaxTotalFee;\n }\n\n function setDepositRevealAheadPeriod(uint32 _depositRevealAheadPeriod)\n external\n {\n self.depositRevealAheadPeriod = _depositRevealAheadPeriod;\n }\n}\n" + }, + "contracts/test/GoerliLightRelay.sol": { + "content": "// SPDX-License-Identifier: GPL-3.0-only\n\n// ██████████████ ▐████▌ ██████████████\n// ██████████████ ▐████▌ ██████████████\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ██████████████ ▐████▌ ██████████████\n// ██████████████ ▐████▌ ██████████████\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n\npragma solidity 0.8.17;\n\nimport {BTCUtils} from \"@keep-network/bitcoin-spv-sol/contracts/BTCUtils.sol\";\n\nimport \"../relay/LightRelay.sol\";\n\n/// @title Goerli Light Relay\n/// @notice GoerliLightRelay is a stub version of LightRelay intended to be\n/// used on the Goerli test network. It allows to set the relay's\n/// difficulty based on arbitrary Bitcoin headers thus effectively\n/// bypass the validation of difficulties of Bitcoin testnet blocks.\n/// Since difficulty in Bitcoin testnet often falls to `1` it would not\n/// be possible to validate blocks with the real LightRelay.\n/// @dev Notice that GoerliLightRelay is derived from LightRelay so that the two\n/// contracts have the same API and correct bindings can be generated.\ncontract GoerliLightRelay is LightRelay {\n using BTCUtils for bytes;\n using BTCUtils for uint256;\n\n /// @notice Sets the current and previous difficulty based on the difficulty\n /// inferred from the provided Bitcoin headers.\n function setDifficultyFromHeaders(bytes memory bitcoinHeaders)\n external\n onlyOwner\n {\n uint256 firstHeaderDiff = bitcoinHeaders\n .extractTarget()\n .calculateDifficulty();\n\n currentEpochDifficulty = firstHeaderDiff;\n prevEpochDifficulty = firstHeaderDiff;\n }\n}\n" + }, + "contracts/test/HeartbeatStub.sol": { + "content": "// SPDX-License-Identifier: GPL-3.0-only\n\npragma solidity 0.8.17;\n\nimport \"../bridge/Heartbeat.sol\";\n\n/// @dev This is a contract implemented to test Heartbeat library directly.\ncontract HeartbeatStub {\n function isValidHeartbeatMessage(bytes calldata message)\n public\n pure\n returns (bool)\n {\n return Heartbeat.isValidHeartbeatMessage(message);\n }\n}\n" + }, + "contracts/test/LightRelayStub.sol": { + "content": "// SPDX-License-Identifier: GPL-3.0-only\n\npragma solidity 0.8.17;\n\nimport \"../relay/LightRelay.sol\";\n\ncontract LightRelayStub is LightRelay {\n // Gas-reporting version of validateChain\n function validateChainGasReport(bytes memory headers)\n external\n returns (uint256, uint256)\n {\n return this.validateChain(headers);\n }\n}\n" + }, + "contracts/test/ReceiveApprovalStub.sol": { + "content": "// SPDX-License-Identifier: GPL-3.0-only\n\npragma solidity 0.8.17;\n\nimport \"../token/TBTC.sol\";\n\ncontract ReceiveApprovalStub is IReceiveApproval {\n bool public shouldRevert;\n\n event ApprovalReceived(\n address from,\n uint256 value,\n address token,\n bytes extraData\n );\n\n function receiveApproval(\n address from,\n uint256 value,\n address token,\n bytes calldata extraData\n ) external override {\n if (shouldRevert) {\n revert(\"i am your father luke\");\n }\n\n emit ApprovalReceived(from, value, token, extraData);\n }\n\n function setShouldRevert(bool _shouldRevert) external {\n shouldRevert = _shouldRevert;\n }\n}\n" + }, + "contracts/test/SystemTestRelay.sol": { + "content": "// SPDX-License-Identifier: GPL-3.0-only\n\npragma solidity 0.8.17;\n\nimport {BTCUtils} from \"@keep-network/bitcoin-spv-sol/contracts/BTCUtils.sol\";\n\nimport \"../bridge/Bridge.sol\";\n\n/// @notice Used only for system tests.\ncontract SystemTestRelay is IRelay {\n using BTCUtils for bytes;\n using BTCUtils for uint256;\n\n uint256 private currentEpochDifficulty;\n uint256 private prevEpochDifficulty;\n\n function setCurrentEpochDifficulty(uint256 _difficulty) external {\n currentEpochDifficulty = _difficulty;\n }\n\n function setPrevEpochDifficulty(uint256 _difficulty) external {\n prevEpochDifficulty = _difficulty;\n }\n\n function setCurrentEpochDifficultyFromHeaders(bytes memory bitcoinHeaders)\n external\n {\n uint256 firstHeaderDiff = bitcoinHeaders\n .extractTarget()\n .calculateDifficulty();\n\n currentEpochDifficulty = firstHeaderDiff;\n }\n\n function setPrevEpochDifficultyFromHeaders(bytes memory bitcoinHeaders)\n external\n {\n uint256 firstHeaderDiff = bitcoinHeaders\n .extractTarget()\n .calculateDifficulty();\n\n prevEpochDifficulty = firstHeaderDiff;\n }\n\n function getCurrentEpochDifficulty()\n external\n view\n override\n returns (uint256)\n {\n return currentEpochDifficulty;\n }\n\n function getPrevEpochDifficulty() external view override returns (uint256) {\n return prevEpochDifficulty;\n }\n}\n" + }, + "contracts/test/TestBitcoinTx.sol": { + "content": "// SPDX-License-Identifier: GPL-3.0-only\n\npragma solidity 0.8.17;\n\nimport \"../bridge/BitcoinTx.sol\";\nimport \"../bridge/BridgeState.sol\";\nimport \"../bridge/IRelay.sol\";\n\ncontract TestBitcoinTx {\n BridgeState.Storage internal self;\n\n event ProofValidated(bytes32 txHash);\n\n constructor(address _relay) {\n self.relay = IRelay(_relay);\n }\n\n function validateProof(\n BitcoinTx.Info calldata txInfo,\n BitcoinTx.Proof calldata proof\n ) external {\n emit ProofValidated(BitcoinTx.validateProof(self, txInfo, proof));\n }\n}\n" + }, + "contracts/test/TestEcdsaLib.sol": { + "content": "// SPDX-License-Identifier: GPL-3.0-only\n\npragma solidity 0.8.17;\n\nimport \"../bridge/EcdsaLib.sol\";\n\n// TODO: Rename to EcdsLibStub\n/// @dev This is a contract implemented to test EcdsaLib library directly.\ncontract TestEcdsaLib {\n function compressPublicKey(bytes32 x, bytes32 y)\n public\n pure\n returns (bytes memory)\n {\n return EcdsaLib.compressPublicKey(x, y);\n }\n}\n" + }, + "contracts/test/TestERC20.sol": { + "content": "// SPDX-License-Identifier: GPL-3.0-only\n\npragma solidity 0.8.17;\n\nimport \"@thesis/solidity-contracts/contracts/token/ERC20WithPermit.sol\";\n\ncontract TestERC20 is ERC20WithPermit {\n string public constant NAME = \"Test ERC20 Token\";\n string public constant SYMBOL = \"TT\";\n\n constructor() ERC20WithPermit(NAME, SYMBOL) {}\n}\n" + }, + "contracts/test/TestERC721.sol": { + "content": "// SPDX-License-Identifier: GPL-3.0-only\n\npragma solidity 0.8.17;\n\nimport \"@openzeppelin/contracts/token/ERC721/ERC721.sol\";\n\ncontract TestERC721 is ERC721 {\n string public constant NAME = \"Test ERC721 Token\";\n string public constant SYMBOL = \"TT\";\n\n constructor() ERC721(NAME, SYMBOL) {}\n\n function mint(address to, uint256 tokenId) public {\n _mint(to, tokenId);\n }\n}\n" + }, + "contracts/test/WormholeBridgeStub.sol": { + "content": "// SPDX-License-Identifier: GPL-3.0-only\n\npragma solidity 0.8.17;\n\nimport \"./TestERC20.sol\";\nimport \"../l2/L2WormholeGateway.sol\";\n\n/// @dev Stub contract used in L2WormholeGateway unit tests.\n/// Stub contract is used instead of a smock because of the token transfer\n/// that needs to happen in completeTransferWithPayload function.\ncontract WormholeBridgeStub is IWormholeTokenBridge {\n TestERC20 public wormholeToken;\n\n uint256 public transferAmount;\n bytes32 public receiverAddress;\n\n // Two simple events allowing to assert Wormhole bridge functions are\n // called.\n event WormholeBridgeStub_completeTransferWithPayload(bytes encodedVm);\n event WormholeBridgeStub_transferTokens(\n address token,\n uint256 amount,\n uint16 recipientChain,\n bytes32 recipient,\n uint256 arbiterFee,\n uint32 nonce\n );\n event WormholeBridgeStub_transferTokensWithPayload(\n address token,\n uint256 amount,\n uint16 recipientChain,\n bytes32 recipient,\n uint32 nonce,\n bytes payload\n );\n\n constructor(TestERC20 _wormholeToken) {\n wormholeToken = _wormholeToken;\n }\n\n function completeTransferWithPayload(bytes memory encodedVm)\n external\n returns (bytes memory)\n {\n emit WormholeBridgeStub_completeTransferWithPayload(encodedVm);\n wormholeToken.mint(msg.sender, transferAmount);\n\n // In a real implementation, encodedVm is parsed. To avoid copy-pasting\n // Wormhole code to this contract and then encoding parmaters in unit\n // tests, we allow to set the receiver address on the stub contract and\n // we return it here. The rest of the parameters does not matter.\n IWormholeTokenBridge.TransferWithPayload memory transfer = IWormholeTokenBridge\n .TransferWithPayload(\n 1, // payloadID\n 2, // amount\n 0x3000000000000000000000000000000000000000000000000000000000000000, // tokenAddress\n 4, // tokenChain\n 0x5000000000000000000000000000000000000000000000000000000000000000, // to\n 6, // toChain\n 0x7000000000000000000000000000000000000000000000000000000000000000, // fromAddress\n abi.encode(receiverAddress) // payload\n );\n\n return abi.encode(transfer);\n }\n\n function transferTokens(\n address token,\n uint256 amount,\n uint16 recipientChain,\n bytes32 recipient,\n uint256 arbiterFee,\n uint32 nonce\n ) external payable returns (uint64 sequence) {\n emit WormholeBridgeStub_transferTokens(\n token,\n amount,\n recipientChain,\n recipient,\n arbiterFee,\n nonce\n );\n return 777;\n }\n\n function transferTokensWithPayload(\n address token,\n uint256 amount,\n uint16 recipientChain,\n bytes32 recipient,\n uint32 nonce,\n bytes memory payload\n ) external payable returns (uint64 sequence) {\n emit WormholeBridgeStub_transferTokensWithPayload(\n token,\n amount,\n recipientChain,\n recipient,\n nonce,\n payload\n );\n return 888;\n }\n\n function parseTransferWithPayload(bytes memory encoded)\n external\n pure\n returns (IWormholeTokenBridge.TransferWithPayload memory transfer)\n {\n return abi.decode(encoded, (IWormholeTokenBridge.TransferWithPayload));\n }\n\n function setTransferAmount(uint256 _transferAmount) external {\n transferAmount = _transferAmount;\n }\n\n function setReceiverAddress(bytes32 _receiverAddress) external {\n receiverAddress = _receiverAddress;\n }\n\n // Allows to mint Wormhole tBTC for depositWormholeTbtc unit tests.\n function mintWormholeToken(address to, uint256 amount) external {\n wormholeToken.mint(to, amount);\n }\n}\n" + }, + "contracts/token/TBTC.sol": { + "content": "// SPDX-License-Identifier: GPL-3.0-only\n\npragma solidity 0.8.17;\n\nimport \"@thesis/solidity-contracts/contracts/token/ERC20WithPermit.sol\";\nimport \"@thesis/solidity-contracts/contracts/token/MisfundRecovery.sol\";\n\ncontract TBTC is ERC20WithPermit, MisfundRecovery {\n constructor() ERC20WithPermit(\"tBTC v2\", \"tBTC\") {}\n}\n" + }, + "contracts/vault/DonationVault.sol": { + "content": "// SPDX-License-Identifier: GPL-3.0-only\n\n// ██████████████ ▐████▌ ██████████████\n// ██████████████ ▐████▌ ██████████████\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ██████████████ ▐████▌ ██████████████\n// ██████████████ ▐████▌ ██████████████\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n\npragma solidity 0.8.17;\n\nimport \"./IVault.sol\";\nimport \"../bank/Bank.sol\";\n\n/// @title BTC donation vault\n/// @notice Vault that allows making BTC donations to the system. Upon deposit,\n/// this vault does not increase depositors' balances and always\n/// decreases its own balance in the same transaction. The vault also\n/// allows making donations using existing Bank balances.\n///\n/// BEWARE: ALL BTC DEPOSITS TARGETING THIS VAULT ARE NOT REDEEMABLE\n/// AND THERE IS NO WAY TO RESTORE THE DONATED BALANCE.\n/// USE THIS VAULT ONLY WHEN YOU REALLY KNOW WHAT YOU ARE DOING!\ncontract DonationVault is IVault {\n Bank public bank;\n\n event DonationReceived(address donor, uint256 donatedAmount);\n\n modifier onlyBank() {\n require(msg.sender == address(bank), \"Caller is not the Bank\");\n _;\n }\n\n constructor(Bank _bank) {\n require(\n address(_bank) != address(0),\n \"Bank can not be the zero address\"\n );\n\n bank = _bank;\n }\n\n /// @notice Transfers the given `amount` of the Bank balance from the\n /// caller to the Donation Vault and immediately decreases the\n /// vault's balance in the Bank by the transferred `amount`.\n /// @param amount Amount of the Bank balance to donate.\n /// @dev Requirements:\n /// - The caller's balance in the Bank must be greater than or equal\n /// to the `amount`,\n /// - Donation Vault must have an allowance for caller's balance in\n /// the Bank for at least `amount`.\n function donate(uint256 amount) external {\n require(\n bank.balanceOf(msg.sender) >= amount,\n \"Amount exceeds balance in the bank\"\n );\n\n emit DonationReceived(msg.sender, amount);\n\n bank.transferBalanceFrom(msg.sender, address(this), amount);\n bank.decreaseBalance(amount);\n }\n\n /// @notice Transfers the given `amount` of the Bank balance from the\n /// `owner` to the Donation Vault and immediately decreases the\n /// vault's balance in the Bank by the transferred `amount`.\n /// @param owner Address of the Bank balance owner who approved their\n /// balance to be used by the vault.\n /// @param amount The amount of the Bank balance approved by the owner\n /// to be used by the vault.\n /// @dev Requirements:\n /// - Can only be called by the Bank via `approveBalanceAndCall`,\n /// - The `owner` balance in the Bank must be greater than or equal\n /// to the `amount`.\n function receiveBalanceApproval(\n address owner,\n uint256 amount,\n bytes memory\n ) external override onlyBank {\n require(\n bank.balanceOf(owner) >= amount,\n \"Amount exceeds balance in the bank\"\n );\n\n emit DonationReceived(owner, amount);\n\n bank.transferBalanceFrom(owner, address(this), amount);\n bank.decreaseBalance(amount);\n }\n\n /// @notice Ignores the deposited amounts and does not increase depositors'\n /// individual balances. The vault decreases its own tBTC balance\n /// in the Bank by the total deposited amount.\n /// @param depositors Addresses of depositors whose deposits have been swept.\n /// @param depositedAmounts Amounts deposited by individual depositors and\n /// swept.\n /// @dev Requirements:\n /// - Can only be called by the Bank after the Bridge swept deposits\n /// and Bank increased balance for the vault,\n /// - The `depositors` array must not be empty,\n /// - The `depositors` array length must be equal to the\n /// `depositedAmounts` array length.\n function receiveBalanceIncrease(\n address[] calldata depositors,\n uint256[] calldata depositedAmounts\n ) external override onlyBank {\n require(depositors.length != 0, \"No depositors specified\");\n\n uint256 totalAmount = 0;\n for (uint256 i = 0; i < depositors.length; i++) {\n totalAmount += depositedAmounts[i];\n emit DonationReceived(depositors[i], depositedAmounts[i]);\n }\n\n bank.decreaseBalance(totalAmount);\n }\n}\n" + }, + "contracts/vault/IVault.sol": { + "content": "// SPDX-License-Identifier: GPL-3.0-only\n\n// ██████████████ ▐████▌ ██████████████\n// ██████████████ ▐████▌ ██████████████\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ██████████████ ▐████▌ ██████████████\n// ██████████████ ▐████▌ ██████████████\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n\npragma solidity 0.8.17;\n\nimport \"../bank/IReceiveBalanceApproval.sol\";\n\n/// @title Bank Vault interface\n/// @notice `IVault` is an interface for a smart contract consuming Bank\n/// balances of other contracts or externally owned accounts (EOA).\ninterface IVault is IReceiveBalanceApproval {\n /// @notice Called by the Bank in `increaseBalanceAndCall` function after\n /// increasing the balance in the Bank for the vault. It happens in\n /// the same transaction in which deposits were swept by the Bridge.\n /// This allows the depositor to route their deposit revealed to the\n /// Bridge to the particular smart contract (vault) in the same\n /// transaction in which the deposit is revealed. This way, the\n /// depositor does not have to execute additional transaction after\n /// the deposit gets swept by the Bridge to approve and transfer\n /// their balance to the vault.\n /// @param depositors Addresses of depositors whose deposits have been swept.\n /// @param depositedAmounts Amounts deposited by individual depositors and\n /// swept.\n /// @dev The implementation must ensure this function can only be called\n /// by the Bank. The Bank guarantees that the vault's balance was\n /// increased by the sum of all deposited amounts before this function\n /// is called, in the same transaction.\n function receiveBalanceIncrease(\n address[] calldata depositors,\n uint256[] calldata depositedAmounts\n ) external;\n}\n" + }, + "contracts/vault/TBTCOptimisticMinting.sol": { + "content": "// SPDX-License-Identifier: GPL-3.0-only\n\n// ██████████████ ▐████▌ ██████████████\n// ██████████████ ▐████▌ ██████████████\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ██████████████ ▐████▌ ██████████████\n// ██████████████ ▐████▌ ██████████████\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n\npragma solidity 0.8.17;\n\nimport \"../bridge/Bridge.sol\";\nimport \"../bridge/Deposit.sol\";\nimport \"../GovernanceUtils.sol\";\n\n/// @title TBTC Optimistic Minting\n/// @notice The Optimistic Minting mechanism allows to mint TBTC before\n/// `TBTCVault` receives the Bank balance. There are two permissioned\n/// sets in the system: Minters and Guardians, both set up in 1-of-n\n/// mode. Minters observe the revealed deposits and request minting TBTC.\n/// Any single Minter can perform this action. There is an\n/// `optimisticMintingDelay` between the time of the request from\n/// a Minter to the time TBTC is minted. During the time of the delay,\n/// any Guardian can cancel the minting.\n/// @dev This functionality is a part of `TBTCVault`. It is implemented in\n/// a separate abstract contract to achieve better separation of concerns\n/// and easier-to-follow code.\nabstract contract TBTCOptimisticMinting is Ownable {\n // Represents optimistic minting request for the given deposit revealed\n // to the Bridge.\n struct OptimisticMintingRequest {\n // UNIX timestamp at which the optimistic minting was requested.\n uint64 requestedAt;\n // UNIX timestamp at which the optimistic minting was finalized.\n // 0 if not yet finalized.\n uint64 finalizedAt;\n }\n\n /// @notice The time delay that needs to pass between initializing and\n /// finalizing the upgrade of governable parameters.\n uint256 public constant GOVERNANCE_DELAY = 24 hours;\n\n /// @notice Multiplier to convert satoshi to TBTC token units.\n uint256 public constant SATOSHI_MULTIPLIER = 10**10;\n\n Bridge public immutable bridge;\n\n /// @notice Indicates if the optimistic minting has been paused. Only the\n /// Governance can pause optimistic minting. Note that the pause of\n /// the optimistic minting does not stop the standard minting flow\n /// where wallets sweep deposits.\n bool public isOptimisticMintingPaused;\n\n /// @notice Divisor used to compute the treasury fee taken from each\n /// optimistically minted deposit and transferred to the treasury\n /// upon finalization of the optimistic mint. This fee is computed\n /// as follows: `fee = amount / optimisticMintingFeeDivisor`.\n /// For example, if the fee needs to be 2%, the\n /// `optimisticMintingFeeDivisor` should be set to `50` because\n /// `1/50 = 0.02 = 2%`.\n /// The optimistic minting fee does not replace the deposit treasury\n /// fee cut by the Bridge. The optimistic fee is a percentage AFTER\n /// the treasury fee is cut:\n /// `optimisticMintingFee = (depositAmount - treasuryFee) / optimisticMintingFeeDivisor`\n uint32 public optimisticMintingFeeDivisor = 500; // 1/500 = 0.002 = 0.2%\n\n /// @notice The time that needs to pass between the moment the optimistic\n /// minting is requested and the moment optimistic minting is\n /// finalized with minting TBTC.\n uint32 public optimisticMintingDelay = 3 hours;\n\n /// @notice Indicates if the given address is a Minter. Only Minters can\n /// request optimistic minting.\n mapping(address => bool) public isMinter;\n\n /// @notice List of all Minters.\n /// @dev May be used to establish an order in which the Minters should\n /// request for an optimistic minting.\n address[] public minters;\n\n /// @notice Indicates if the given address is a Guardian. Only Guardians can\n /// cancel requested optimistic minting.\n mapping(address => bool) public isGuardian;\n\n /// @notice Collection of all revealed deposits for which the optimistic\n /// minting was requested. Indexed by a deposit key computed as\n /// `keccak256(fundingTxHash | fundingOutputIndex)`.\n mapping(uint256 => OptimisticMintingRequest)\n public optimisticMintingRequests;\n\n /// @notice Optimistic minting debt value per depositor's address. The debt\n /// represents the total value of all depositor's deposits revealed\n /// to the Bridge that has not been yet swept and led to the\n /// optimistic minting of TBTC. When `TBTCVault` sweeps a deposit,\n /// the debt is fully or partially paid off, no matter if that\n /// particular swept deposit was used for the optimistic minting or\n /// not. The values are in 1e18 Ethereum precision.\n mapping(address => uint256) public optimisticMintingDebt;\n\n /// @notice New optimistic minting fee divisor value. Set only when the\n /// parameter update process is pending. Once the update gets\n // finalized, this will be the value of the divisor.\n uint32 public newOptimisticMintingFeeDivisor;\n /// @notice The timestamp at which the update of the optimistic minting fee\n /// divisor started. Zero if update is not in progress.\n uint256 public optimisticMintingFeeUpdateInitiatedTimestamp;\n\n /// @notice New optimistic minting delay value. Set only when the parameter\n /// update process is pending. Once the update gets finalized, this\n // will be the value of the delay.\n uint32 public newOptimisticMintingDelay;\n /// @notice The timestamp at which the update of the optimistic minting\n /// delay started. Zero if update is not in progress.\n uint256 public optimisticMintingDelayUpdateInitiatedTimestamp;\n\n event OptimisticMintingRequested(\n address indexed minter,\n uint256 indexed depositKey,\n address indexed depositor,\n uint256 amount, // amount in 1e18 Ethereum precision\n bytes32 fundingTxHash,\n uint32 fundingOutputIndex\n );\n event OptimisticMintingFinalized(\n address indexed minter,\n uint256 indexed depositKey,\n address indexed depositor,\n uint256 optimisticMintingDebt\n );\n event OptimisticMintingCancelled(\n address indexed guardian,\n uint256 indexed depositKey\n );\n event OptimisticMintingDebtRepaid(\n address indexed depositor,\n uint256 optimisticMintingDebt\n );\n event MinterAdded(address indexed minter);\n event MinterRemoved(address indexed minter);\n event GuardianAdded(address indexed guardian);\n event GuardianRemoved(address indexed guardian);\n event OptimisticMintingPaused();\n event OptimisticMintingUnpaused();\n\n event OptimisticMintingFeeUpdateStarted(\n uint32 newOptimisticMintingFeeDivisor\n );\n event OptimisticMintingFeeUpdated(uint32 newOptimisticMintingFeeDivisor);\n\n event OptimisticMintingDelayUpdateStarted(uint32 newOptimisticMintingDelay);\n event OptimisticMintingDelayUpdated(uint32 newOptimisticMintingDelay);\n\n modifier onlyMinter() {\n require(isMinter[msg.sender], \"Caller is not a minter\");\n _;\n }\n\n modifier onlyGuardian() {\n require(isGuardian[msg.sender], \"Caller is not a guardian\");\n _;\n }\n\n modifier onlyOwnerOrGuardian() {\n require(\n owner() == msg.sender || isGuardian[msg.sender],\n \"Caller is not the owner or guardian\"\n );\n _;\n }\n\n modifier whenOptimisticMintingNotPaused() {\n require(!isOptimisticMintingPaused, \"Optimistic minting paused\");\n _;\n }\n\n modifier onlyAfterGovernanceDelay(uint256 updateInitiatedTimestamp) {\n GovernanceUtils.onlyAfterGovernanceDelay(\n updateInitiatedTimestamp,\n GOVERNANCE_DELAY\n );\n _;\n }\n\n constructor(Bridge _bridge) {\n require(\n address(_bridge) != address(0),\n \"Bridge can not be the zero address\"\n );\n\n bridge = _bridge;\n }\n\n /// @dev Mints the given amount of TBTC to the given depositor's address.\n /// Implemented by TBTCVault.\n function _mint(address minter, uint256 amount) internal virtual;\n\n /// @notice Allows to fetch a list of all Minters.\n function getMinters() external view returns (address[] memory) {\n return minters;\n }\n\n /// @notice Allows a Minter to request for an optimistic minting of TBTC.\n /// The following conditions must be met:\n /// - There is no optimistic minting request for the deposit,\n /// finalized or not.\n /// - The deposit with the given Bitcoin funding transaction hash\n /// and output index has been revealed to the Bridge.\n /// - The deposit has not been swept yet.\n /// - The deposit is targeted into the TBTCVault.\n /// - The optimistic minting is not paused.\n /// After calling this function, the Minter has to wait for\n /// `optimisticMintingDelay` before finalizing the mint with a call\n /// to finalizeOptimisticMint.\n /// @dev The deposit done on the Bitcoin side must be revealed early enough\n /// to the Bridge on Ethereum to pass the Bridge's validation. The\n /// validation passes successfully only if the deposit reveal is done\n /// respectively earlier than the moment when the deposit refund\n /// locktime is reached, i.e. the deposit becomes refundable. It may\n /// happen that the wallet does not sweep a revealed deposit and one of\n /// the Minters requests an optimistic mint for that deposit just\n /// before the locktime is reached. Guardians must cancel optimistic\n /// minting for this deposit because the wallet will not be able to\n /// sweep it. The on-chain optimistic minting code does not perform any\n /// validation for gas efficiency: it would have to perform the same\n /// validation as `validateDepositRefundLocktime` and expect the entire\n /// `DepositRevealInfo` to be passed to assemble the expected script\n /// hash on-chain. Guardians must validate if the deposit happened on\n /// Bitcoin, that the script hash has the expected format, and that the\n /// wallet is an active one so they can also validate the time left for\n /// the refund.\n function requestOptimisticMint(\n bytes32 fundingTxHash,\n uint32 fundingOutputIndex\n ) external onlyMinter whenOptimisticMintingNotPaused {\n uint256 depositKey = calculateDepositKey(\n fundingTxHash,\n fundingOutputIndex\n );\n\n OptimisticMintingRequest storage request = optimisticMintingRequests[\n depositKey\n ];\n require(\n request.requestedAt == 0,\n \"Optimistic minting already requested for the deposit\"\n );\n\n Deposit.DepositRequest memory deposit = bridge.deposits(depositKey);\n\n require(deposit.revealedAt != 0, \"The deposit has not been revealed\");\n require(deposit.sweptAt == 0, \"The deposit is already swept\");\n require(deposit.vault == address(this), \"Unexpected vault address\");\n\n /* solhint-disable-next-line not-rely-on-time */\n request.requestedAt = uint64(block.timestamp);\n\n emit OptimisticMintingRequested(\n msg.sender,\n depositKey,\n deposit.depositor,\n deposit.amount * SATOSHI_MULTIPLIER,\n fundingTxHash,\n fundingOutputIndex\n );\n }\n\n /// @notice Allows a Minter to finalize previously requested optimistic\n /// minting. The following conditions must be met:\n /// - The optimistic minting has been requested for the given\n /// deposit.\n /// - The deposit has not been swept yet.\n /// - At least `optimisticMintingDelay` passed since the optimistic\n /// minting was requested for the given deposit.\n /// - The optimistic minting has not been finalized earlier for the\n /// given deposit.\n /// - The optimistic minting request for the given deposit has not\n /// been canceled by a Guardian.\n /// - The optimistic minting is not paused.\n /// This function mints TBTC and increases `optimisticMintingDebt`\n /// for the given depositor. The optimistic minting request is\n /// marked as finalized.\n function finalizeOptimisticMint(\n bytes32 fundingTxHash,\n uint32 fundingOutputIndex\n ) external onlyMinter whenOptimisticMintingNotPaused {\n uint256 depositKey = calculateDepositKey(\n fundingTxHash,\n fundingOutputIndex\n );\n\n OptimisticMintingRequest storage request = optimisticMintingRequests[\n depositKey\n ];\n require(\n request.requestedAt != 0,\n \"Optimistic minting not requested for the deposit\"\n );\n require(\n request.finalizedAt == 0,\n \"Optimistic minting already finalized for the deposit\"\n );\n\n require(\n /* solhint-disable-next-line not-rely-on-time */\n block.timestamp > request.requestedAt + optimisticMintingDelay,\n \"Optimistic minting delay has not passed yet\"\n );\n\n Deposit.DepositRequest memory deposit = bridge.deposits(depositKey);\n require(deposit.sweptAt == 0, \"The deposit is already swept\");\n\n // Bridge, when sweeping, cuts a deposit treasury fee and splits\n // Bitcoin miner fee for the sweep transaction evenly between the\n // depositors in the sweep.\n //\n // When tokens are optimistically minted, we do not know what the\n // Bitcoin miner fee for the sweep transaction will look like.\n // The Bitcoin miner fee is ignored. When sweeping, the miner fee is\n // subtracted so the optimisticMintingDebt may stay non-zero after the\n // deposit is swept.\n //\n // This imbalance is supposed to be solved by a donation to the Bridge.\n uint256 amountToMint = (deposit.amount - deposit.treasuryFee) *\n SATOSHI_MULTIPLIER;\n\n // The Optimistic Minting mechanism may additionally cut a fee from the\n // amount that is left after deducting the Bridge deposit treasury fee.\n // Think of this fee as an extra payment for faster processing of\n // deposits. One does not need to use the Optimistic Minting mechanism\n // and they may wait for the Bridge to sweep their deposit if they do\n // not want to pay the Optimistic Minting fee.\n uint256 optimisticMintFee = optimisticMintingFeeDivisor > 0\n ? (amountToMint / optimisticMintingFeeDivisor)\n : 0;\n\n // Both the optimistic minting fee and the share that goes to the\n // depositor are optimistically minted. All TBTC that is optimistically\n // minted should be added to the optimistic minting debt. When the\n // deposit is swept, it is paying off both the depositor's share and the\n // treasury's share (optimistic minting fee).\n uint256 newDebt = optimisticMintingDebt[deposit.depositor] +\n amountToMint;\n optimisticMintingDebt[deposit.depositor] = newDebt;\n\n _mint(deposit.depositor, amountToMint - optimisticMintFee);\n if (optimisticMintFee > 0) {\n _mint(bridge.treasury(), optimisticMintFee);\n }\n\n /* solhint-disable-next-line not-rely-on-time */\n request.finalizedAt = uint64(block.timestamp);\n\n emit OptimisticMintingFinalized(\n msg.sender,\n depositKey,\n deposit.depositor,\n newDebt\n );\n }\n\n /// @notice Allows a Guardian to cancel optimistic minting request. The\n /// following conditions must be met:\n /// - The optimistic minting request for the given deposit exists.\n /// - The optimistic minting request for the given deposit has not\n /// been finalized yet.\n /// Optimistic minting request is removed. It is possible to request\n /// optimistic minting again for the same deposit later.\n /// @dev Guardians must validate the following conditions for every deposit\n /// for which the optimistic minting was requested:\n /// - The deposit happened on Bitcoin side and it has enough\n /// confirmations.\n /// - The optimistic minting has been requested early enough so that\n /// the wallet has enough time to sweep the deposit.\n /// - The wallet is an active one and it does perform sweeps or it will\n /// perform sweeps once the sweeps are activated.\n function cancelOptimisticMint(\n bytes32 fundingTxHash,\n uint32 fundingOutputIndex\n ) external onlyGuardian {\n uint256 depositKey = calculateDepositKey(\n fundingTxHash,\n fundingOutputIndex\n );\n\n OptimisticMintingRequest storage request = optimisticMintingRequests[\n depositKey\n ];\n require(\n request.requestedAt != 0,\n \"Optimistic minting not requested for the deposit\"\n );\n require(\n request.finalizedAt == 0,\n \"Optimistic minting already finalized for the deposit\"\n );\n\n // Delete it. It allows to request optimistic minting for the given\n // deposit again. Useful in case of an errant Guardian.\n delete optimisticMintingRequests[depositKey];\n\n emit OptimisticMintingCancelled(msg.sender, depositKey);\n }\n\n /// @notice Adds the address to the Minter list.\n function addMinter(address minter) external onlyOwner {\n require(!isMinter[minter], \"This address is already a minter\");\n isMinter[minter] = true;\n minters.push(minter);\n emit MinterAdded(minter);\n }\n\n /// @notice Removes the address from the Minter list.\n function removeMinter(address minter) external onlyOwnerOrGuardian {\n require(isMinter[minter], \"This address is not a minter\");\n delete isMinter[minter];\n\n // We do not expect too many Minters so a simple loop is safe.\n for (uint256 i = 0; i < minters.length; i++) {\n if (minters[i] == minter) {\n minters[i] = minters[minters.length - 1];\n // slither-disable-next-line costly-loop\n minters.pop();\n break;\n }\n }\n\n emit MinterRemoved(minter);\n }\n\n /// @notice Adds the address to the Guardian set.\n function addGuardian(address guardian) external onlyOwner {\n require(!isGuardian[guardian], \"This address is already a guardian\");\n isGuardian[guardian] = true;\n emit GuardianAdded(guardian);\n }\n\n /// @notice Removes the address from the Guardian set.\n function removeGuardian(address guardian) external onlyOwner {\n require(isGuardian[guardian], \"This address is not a guardian\");\n delete isGuardian[guardian];\n emit GuardianRemoved(guardian);\n }\n\n /// @notice Pauses the optimistic minting. Note that the pause of the\n /// optimistic minting does not stop the standard minting flow\n /// where wallets sweep deposits.\n function pauseOptimisticMinting() external onlyOwner {\n require(\n !isOptimisticMintingPaused,\n \"Optimistic minting already paused\"\n );\n isOptimisticMintingPaused = true;\n emit OptimisticMintingPaused();\n }\n\n /// @notice Unpauses the optimistic minting.\n function unpauseOptimisticMinting() external onlyOwner {\n require(isOptimisticMintingPaused, \"Optimistic minting is not paused\");\n isOptimisticMintingPaused = false;\n emit OptimisticMintingUnpaused();\n }\n\n /// @notice Begins the process of updating optimistic minting fee.\n /// The fee is computed as follows:\n /// `fee = amount / optimisticMintingFeeDivisor`.\n /// For example, if the fee needs to be 2% of each deposit,\n /// the `optimisticMintingFeeDivisor` should be set to `50` because\n /// `1/50 = 0.02 = 2%`.\n /// @dev See the documentation for optimisticMintingFeeDivisor.\n function beginOptimisticMintingFeeUpdate(\n uint32 _newOptimisticMintingFeeDivisor\n ) external onlyOwner {\n /* solhint-disable-next-line not-rely-on-time */\n optimisticMintingFeeUpdateInitiatedTimestamp = block.timestamp;\n newOptimisticMintingFeeDivisor = _newOptimisticMintingFeeDivisor;\n emit OptimisticMintingFeeUpdateStarted(_newOptimisticMintingFeeDivisor);\n }\n\n /// @notice Finalizes the update process of the optimistic minting fee.\n function finalizeOptimisticMintingFeeUpdate()\n external\n onlyOwner\n onlyAfterGovernanceDelay(optimisticMintingFeeUpdateInitiatedTimestamp)\n {\n optimisticMintingFeeDivisor = newOptimisticMintingFeeDivisor;\n emit OptimisticMintingFeeUpdated(newOptimisticMintingFeeDivisor);\n\n newOptimisticMintingFeeDivisor = 0;\n optimisticMintingFeeUpdateInitiatedTimestamp = 0;\n }\n\n /// @notice Begins the process of updating optimistic minting delay.\n function beginOptimisticMintingDelayUpdate(\n uint32 _newOptimisticMintingDelay\n ) external onlyOwner {\n /* solhint-disable-next-line not-rely-on-time */\n optimisticMintingDelayUpdateInitiatedTimestamp = block.timestamp;\n newOptimisticMintingDelay = _newOptimisticMintingDelay;\n emit OptimisticMintingDelayUpdateStarted(_newOptimisticMintingDelay);\n }\n\n /// @notice Finalizes the update process of the optimistic minting delay.\n function finalizeOptimisticMintingDelayUpdate()\n external\n onlyOwner\n onlyAfterGovernanceDelay(optimisticMintingDelayUpdateInitiatedTimestamp)\n {\n optimisticMintingDelay = newOptimisticMintingDelay;\n emit OptimisticMintingDelayUpdated(newOptimisticMintingDelay);\n\n newOptimisticMintingDelay = 0;\n optimisticMintingDelayUpdateInitiatedTimestamp = 0;\n }\n\n /// @notice Calculates deposit key the same way as the Bridge contract.\n /// The deposit key is computed as\n /// `keccak256(fundingTxHash | fundingOutputIndex)`.\n function calculateDepositKey(\n bytes32 fundingTxHash,\n uint32 fundingOutputIndex\n ) public pure returns (uint256) {\n return\n uint256(\n keccak256(abi.encodePacked(fundingTxHash, fundingOutputIndex))\n );\n }\n\n /// @notice Used by `TBTCVault.receiveBalanceIncrease` to repay the optimistic\n /// minting debt before TBTC is minted. When optimistic minting is\n /// finalized, debt equal to the value of the deposit being\n /// a subject of the optimistic minting is incurred. When `TBTCVault`\n /// sweeps a deposit, the debt is fully or partially paid off, no\n /// matter if that particular deposit was used for the optimistic\n /// minting or not.\n /// @dev See `TBTCVault.receiveBalanceIncrease`\n /// @param depositor The depositor whose balance increase is received.\n /// @param amount The balance increase amount for the depositor received.\n /// @return The TBTC amount that should be minted after paying off the\n /// optimistic minting debt.\n function repayOptimisticMintingDebt(address depositor, uint256 amount)\n internal\n returns (uint256)\n {\n uint256 debt = optimisticMintingDebt[depositor];\n if (debt == 0) {\n return amount;\n }\n\n if (amount > debt) {\n optimisticMintingDebt[depositor] = 0;\n emit OptimisticMintingDebtRepaid(depositor, 0);\n return amount - debt;\n } else {\n optimisticMintingDebt[depositor] = debt - amount;\n emit OptimisticMintingDebtRepaid(depositor, debt - amount);\n return 0;\n }\n }\n}\n" + }, + "contracts/vault/TBTCVault.sol": { + "content": "// SPDX-License-Identifier: GPL-3.0-only\n\n// ██████████████ ▐████▌ ██████████████\n// ██████████████ ▐████▌ ██████████████\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ██████████████ ▐████▌ ██████████████\n// ██████████████ ▐████▌ ██████████████\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n// ▐████▌ ▐████▌\n\npragma solidity 0.8.17;\n\nimport \"@openzeppelin/contracts/access/Ownable.sol\";\n\nimport \"./IVault.sol\";\nimport \"./TBTCOptimisticMinting.sol\";\nimport \"../bank/Bank.sol\";\nimport \"../token/TBTC.sol\";\n\n/// @title TBTC application vault\n/// @notice TBTC is a fully Bitcoin-backed ERC-20 token pegged to the price of\n/// Bitcoin. It facilitates Bitcoin holders to act on the Ethereum\n/// blockchain and access the decentralized finance (DeFi) ecosystem.\n/// TBTC Vault mints and unmints TBTC based on Bitcoin balances in the\n/// Bank.\n/// @dev TBTC Vault is the owner of TBTC token contract and is the only contract\n/// minting the token.\ncontract TBTCVault is IVault, Ownable, TBTCOptimisticMinting {\n using SafeERC20 for IERC20;\n\n Bank public immutable bank;\n TBTC public immutable tbtcToken;\n\n /// @notice The address of a new TBTC vault. Set only when the upgrade\n /// process is pending. Once the upgrade gets finalized, the new\n /// TBTC vault will become an owner of TBTC token.\n address public newVault;\n /// @notice The timestamp at which an upgrade to a new TBTC vault was\n /// initiated. Set only when the upgrade process is pending.\n uint256 public upgradeInitiatedTimestamp;\n\n event Minted(address indexed to, uint256 amount);\n event Unminted(address indexed from, uint256 amount);\n\n event UpgradeInitiated(address newVault, uint256 timestamp);\n event UpgradeFinalized(address newVault);\n\n modifier onlyBank() {\n require(msg.sender == address(bank), \"Caller is not the Bank\");\n _;\n }\n\n constructor(\n Bank _bank,\n TBTC _tbtcToken,\n Bridge _bridge\n ) TBTCOptimisticMinting(_bridge) {\n require(\n address(_bank) != address(0),\n \"Bank can not be the zero address\"\n );\n\n require(\n address(_tbtcToken) != address(0),\n \"TBTC token can not be the zero address\"\n );\n\n bank = _bank;\n tbtcToken = _tbtcToken;\n }\n\n /// @notice Mints the given `amount` of TBTC to the caller previously\n /// transferring `amount / SATOSHI_MULTIPLIER` of the Bank balance\n /// from caller to TBTC Vault. If `amount` is not divisible by\n /// SATOSHI_MULTIPLIER, the remainder is left on the caller's\n /// Bank balance.\n /// @dev TBTC Vault must have an allowance for caller's balance in the\n /// Bank for at least `amount / SATOSHI_MULTIPLIER`.\n /// @param amount Amount of TBTC to mint.\n function mint(uint256 amount) external {\n (uint256 convertibleAmount, , uint256 satoshis) = amountToSatoshis(\n amount\n );\n\n require(\n bank.balanceOf(msg.sender) >= satoshis,\n \"Amount exceeds balance in the bank\"\n );\n _mint(msg.sender, convertibleAmount);\n bank.transferBalanceFrom(msg.sender, address(this), satoshis);\n }\n\n /// @notice Transfers `satoshis` of the Bank balance from the caller\n /// to TBTC Vault and mints `satoshis * SATOSHI_MULTIPLIER` of TBTC\n /// to the caller.\n /// @dev Can only be called by the Bank via `approveBalanceAndCall`.\n /// @param owner The owner who approved their Bank balance.\n /// @param satoshis Amount of satoshis used to mint TBTC.\n function receiveBalanceApproval(\n address owner,\n uint256 satoshis,\n bytes calldata\n ) external override onlyBank {\n require(\n bank.balanceOf(owner) >= satoshis,\n \"Amount exceeds balance in the bank\"\n );\n _mint(owner, satoshis * SATOSHI_MULTIPLIER);\n bank.transferBalanceFrom(owner, address(this), satoshis);\n }\n\n /// @notice Mints the same amount of TBTC as the deposited satoshis amount\n /// multiplied by SATOSHI_MULTIPLIER for each depositor in the array.\n /// Can only be called by the Bank after the Bridge swept deposits\n /// and Bank increased balance for the vault.\n /// @dev Fails if `depositors` array is empty. Expects the length of\n /// `depositors` and `depositedSatoshiAmounts` is the same.\n function receiveBalanceIncrease(\n address[] calldata depositors,\n uint256[] calldata depositedSatoshiAmounts\n ) external override onlyBank {\n require(depositors.length != 0, \"No depositors specified\");\n for (uint256 i = 0; i < depositors.length; i++) {\n address depositor = depositors[i];\n uint256 satoshis = depositedSatoshiAmounts[i];\n _mint(\n depositor,\n repayOptimisticMintingDebt(\n depositor,\n satoshis * SATOSHI_MULTIPLIER\n )\n );\n }\n }\n\n /// @notice Burns `amount` of TBTC from the caller's balance and transfers\n /// `amount / SATOSHI_MULTIPLIER` back to the caller's balance in\n /// the Bank. If `amount` is not divisible by SATOSHI_MULTIPLIER,\n /// the remainder is left on the caller's account.\n /// @dev Caller must have at least `amount` of TBTC approved to\n /// TBTC Vault.\n /// @param amount Amount of TBTC to unmint.\n function unmint(uint256 amount) external {\n (uint256 convertibleAmount, , ) = amountToSatoshis(amount);\n\n _unmint(msg.sender, convertibleAmount);\n }\n\n /// @notice Burns `amount` of TBTC from the caller's balance and transfers\n /// `amount / SATOSHI_MULTIPLIER` of Bank balance to the Bridge\n /// requesting redemption based on the provided `redemptionData`.\n /// If `amount` is not divisible by SATOSHI_MULTIPLIER, the\n /// remainder is left on the caller's account.\n /// @dev Caller must have at least `amount` of TBTC approved to\n /// TBTC Vault.\n /// @param amount Amount of TBTC to unmint and request to redeem in Bridge.\n /// @param redemptionData Redemption data in a format expected from\n /// `redemptionData` parameter of Bridge's `receiveBalanceApproval`\n /// function.\n function unmintAndRedeem(uint256 amount, bytes calldata redemptionData)\n external\n {\n (uint256 convertibleAmount, , ) = amountToSatoshis(amount);\n\n _unmintAndRedeem(msg.sender, convertibleAmount, redemptionData);\n }\n\n /// @notice Burns `amount` of TBTC from the caller's balance. If `extraData`\n /// is empty, transfers `amount` back to the caller's balance in the\n /// Bank. If `extraData` is not empty, requests redemption in the\n /// Bridge using the `extraData` as a `redemptionData` parameter to\n /// Bridge's `receiveBalanceApproval` function.\n /// If `amount` is not divisible by SATOSHI_MULTIPLIER, the\n /// remainder is left on the caller's account. Note that it may\n /// left a token approval equal to the remainder.\n /// @dev This function is doing the same as `unmint` or `unmintAndRedeem`\n /// (depending on `extraData` parameter) but it allows to execute\n /// unminting without a separate approval transaction. The function can\n /// be called only via `approveAndCall` of TBTC token.\n /// @param from TBTC token holder executing unminting.\n /// @param amount Amount of TBTC to unmint.\n /// @param token TBTC token address.\n /// @param extraData Redemption data in a format expected from\n /// `redemptionData` parameter of Bridge's `receiveBalanceApproval`\n /// function. If empty, `receiveApproval` is not requesting a\n /// redemption of Bank balance but is instead performing just TBTC\n /// unminting to a Bank balance.\n function receiveApproval(\n address from,\n uint256 amount,\n address token,\n bytes calldata extraData\n ) external {\n require(token == address(tbtcToken), \"Token is not TBTC\");\n require(msg.sender == token, \"Only TBTC caller allowed\");\n (uint256 convertibleAmount, , ) = amountToSatoshis(amount);\n if (extraData.length == 0) {\n _unmint(from, convertibleAmount);\n } else {\n _unmintAndRedeem(from, convertibleAmount, extraData);\n }\n }\n\n /// @notice Initiates vault upgrade process. The upgrade process needs to be\n /// finalized with a call to `finalizeUpgrade` function after the\n /// `UPGRADE_GOVERNANCE_DELAY` passes. Only the governance can\n /// initiate the upgrade.\n /// @param _newVault The new vault address.\n function initiateUpgrade(address _newVault) external onlyOwner {\n require(_newVault != address(0), \"New vault address cannot be zero\");\n /* solhint-disable-next-line not-rely-on-time */\n emit UpgradeInitiated(_newVault, block.timestamp);\n /* solhint-disable-next-line not-rely-on-time */\n upgradeInitiatedTimestamp = block.timestamp;\n newVault = _newVault;\n }\n\n /// @notice Allows the governance to finalize vault upgrade process. The\n /// upgrade process needs to be first initiated with a call to\n /// `initiateUpgrade` and the `GOVERNANCE_DELAY` needs to pass.\n /// Once the upgrade is finalized, the new vault becomes the owner\n /// of the TBTC token and receives the whole Bank balance of this\n /// vault.\n function finalizeUpgrade()\n external\n onlyOwner\n onlyAfterGovernanceDelay(upgradeInitiatedTimestamp)\n {\n emit UpgradeFinalized(newVault);\n // slither-disable-next-line reentrancy-no-eth\n tbtcToken.transferOwnership(newVault);\n bank.transferBalance(newVault, bank.balanceOf(address(this)));\n newVault = address(0);\n upgradeInitiatedTimestamp = 0;\n }\n\n /// @notice Allows the governance of the TBTCVault to recover any ERC20\n /// token sent mistakenly to the TBTC token contract address.\n /// @param token Address of the recovered ERC20 token contract.\n /// @param recipient Address the recovered token should be sent to.\n /// @param amount Recovered amount.\n function recoverERC20FromToken(\n IERC20 token,\n address recipient,\n uint256 amount\n ) external onlyOwner {\n tbtcToken.recoverERC20(token, recipient, amount);\n }\n\n /// @notice Allows the governance of the TBTCVault to recover any ERC721\n /// token sent mistakenly to the TBTC token contract address.\n /// @param token Address of the recovered ERC721 token contract.\n /// @param recipient Address the recovered token should be sent to.\n /// @param tokenId Identifier of the recovered token.\n /// @param data Additional data.\n function recoverERC721FromToken(\n IERC721 token,\n address recipient,\n uint256 tokenId,\n bytes calldata data\n ) external onlyOwner {\n tbtcToken.recoverERC721(token, recipient, tokenId, data);\n }\n\n /// @notice Allows the governance of the TBTCVault to recover any ERC20\n /// token sent - mistakenly or not - to the vault address. This\n /// function should be used to withdraw TBTC v1 tokens transferred\n /// to TBTCVault as a result of VendingMachine > TBTCVault upgrade.\n /// @param token Address of the recovered ERC20 token contract.\n /// @param recipient Address the recovered token should be sent to.\n /// @param amount Recovered amount.\n function recoverERC20(\n IERC20 token,\n address recipient,\n uint256 amount\n ) external onlyOwner {\n token.safeTransfer(recipient, amount);\n }\n\n /// @notice Allows the governance of the TBTCVault to recover any ERC721\n /// token sent mistakenly to the vault address.\n /// @param token Address of the recovered ERC721 token contract.\n /// @param recipient Address the recovered token should be sent to.\n /// @param tokenId Identifier of the recovered token.\n /// @param data Additional data.\n function recoverERC721(\n IERC721 token,\n address recipient,\n uint256 tokenId,\n bytes calldata data\n ) external onlyOwner {\n token.safeTransferFrom(address(this), recipient, tokenId, data);\n }\n\n /// @notice Returns the amount of TBTC to be minted/unminted, the remainder,\n /// and the Bank balance to be transferred for the given mint/unmint.\n /// Note that if the `amount` is not divisible by SATOSHI_MULTIPLIER,\n /// the remainder is left on the caller's account when minting or\n /// unminting.\n /// @return convertibleAmount Amount of TBTC to be minted/unminted.\n /// @return remainder Not convertible remainder if amount is not divisible\n /// by SATOSHI_MULTIPLIER.\n /// @return satoshis Amount in satoshis - the Bank balance to be transferred\n /// for the given mint/unmint\n function amountToSatoshis(uint256 amount)\n public\n view\n returns (\n uint256 convertibleAmount,\n uint256 remainder,\n uint256 satoshis\n )\n {\n remainder = amount % SATOSHI_MULTIPLIER;\n convertibleAmount = amount - remainder;\n satoshis = convertibleAmount / SATOSHI_MULTIPLIER;\n }\n\n // slither-disable-next-line calls-loop\n function _mint(address minter, uint256 amount) internal override {\n emit Minted(minter, amount);\n tbtcToken.mint(minter, amount);\n }\n\n /// @dev `amount` MUST be divisible by SATOSHI_MULTIPLIER with no change.\n function _unmint(address unminter, uint256 amount) internal {\n emit Unminted(unminter, amount);\n tbtcToken.burnFrom(unminter, amount);\n bank.transferBalance(unminter, amount / SATOSHI_MULTIPLIER);\n }\n\n /// @dev `amount` MUST be divisible by SATOSHI_MULTIPLIER with no change.\n function _unmintAndRedeem(\n address redeemer,\n uint256 amount,\n bytes calldata redemptionData\n ) internal {\n emit Unminted(redeemer, amount);\n tbtcToken.burnFrom(redeemer, amount);\n bank.approveBalanceAndCall(\n address(bridge),\n amount / SATOSHI_MULTIPLIER,\n redemptionData\n );\n }\n}\n" + } + }, + "settings": { + "optimizer": { + "enabled": true, + "runs": 1000 + }, + "outputSelection": { + "*": { + "*": [ + "abi", + "evm.bytecode", + "evm.deployedBytecode", + "evm.methodIdentifiers", + "metadata", + "storageLayout", + "devdoc", + "userdoc", + "evm.gasEstimates" + ], + "": [ + "ast" + ] + } + }, + "metadata": { + "useLiteralContent": true + } + } +} \ No newline at end of file